Skip to main content

Scheduling and cancellation

Scheduling uses the existing estimate/quote/submit flow. First check broadcaster_getStatus.scheduling.enabled. Report unsupported capability explicitly rather than falling back to immediate sending. Actual deployment determines availability.

Discover limits and sign the time window​

Status scheduling contains enabled and decimal-string maxDelaySeconds, defaultExecutionWindowSeconds, maxExecutionWindowSeconds, and minDeadlineSlackSeconds. Defaults are 604800, 300, 3600, and 120 seconds respectively. Operators can change them; use the advertised capabilities rather than hardcoding a seven-day limit.

schedule fieldWire formatMeaning
publishAfterDecimal-string Unix secondsEarliest time to begin broadcasting
executeBeforeDecimal-string Unix secondsExclusive end of the broadcast-start window
cancelTokenHashNonzero lowercase 0x bytes32Keccak256 of the locally retained random cancellation token

Pass schedule to both estimateQuote and getQuote. Returned quote.schedule is signed with the separate ScheduledQuote EIP-712 type. Submission takes timing exclusively from the quote and accepts no extra unsigned schedule. Removing schedule or changing times invalidates the signature.

The following is a structural illustration, not a sendable request. Data, hashes, and times must come from the matching SDK and actual intent. Build the complete request with the matching SDK, then initiate quoting and submission through the application’s user-confirmation flow.

params: [{
data: SDK-generated canonical calldata,
schedule: {
publishAfter: future Unix seconds as a decimal string,
executeBefore: exclusive window end as a decimal string,
cancelTokenHash: Keccak256 of locally saved random 32-byte token
}
}]

The admission quote lasts at most five minutes, bounded by price and intent expiry. An accepted schedule does not disappear when that admission quote later expires, and scheduling does not extend on-chain authorization. Intent, actual funding authorizations, and Permit must cover executeBefore plus advertised slack.

A window is not an inclusion guarantee​

The service sends nothing before publishAfter and does not include an undued member in a due aggregate. When due, it rechecks balances, allowance, inputs, roots, simulation, and required Provenance. Temporary failures can retry within the window; rejection cannot become allowance. Missing the window produces expired.

The window constrains broadcast start rather than block inclusion. Work that acquired send rights or was broadcast continues receipt/finality reconciliation. The relay cannot raise fees or change the recipient to make scheduled execution succeed.

Cancellation tokens and races​

The SDK generates and retains a random 32-byte cancelToken locally; only its Keccak256 appears in the quote. Before submitting, save the token, schedule terms, service scope, and full frozen body. Save the service-issued durable id when the response arrives.

Remote cancellation calls broadcaster_cancelTransaction with params [{id,cancelToken}]. The token is an authorization secret and belongs in neither logs, public status, nor analytics events. Possessing the id alone grants no cancellation authority.

Current stateCan it be cancelled?
scheduled / preparingYes, if cancellation wins before durable send reservation
queued / provingOnly explicitly scheduled jobs without send rights or frozen batch assignment
pending / submitted / uncertainNo, even when no transaction hash is available yet
cancelledRepeating the correct credential is idempotent
expired / rejected / confirmed / revertedCannot be cancelled again or revived

Cancellation and acquisition of send rights compete for the same durable state transition. Show success only after cancellation persists; earlier simulation/proving results can then no longer send. Successful cancellation binds this Broadcaster only. It does not revoke Protocol signatures or stop another holder broadcasting the original transaction.

Recovery and errors​

If the submit response is lost before the id is known, replay the original saved submission to recover the service id before querying or cancelling. cancelToken alone is insufficient; do not derive a job ID from a local hash. A local preparation never submitted has no remote job.

ErrorAction
-32602Fix malformed parameters
-32020Unknown job or invalid credential; deliberately indistinguishable
-32021Too late; continue observing the original job
-32022Cancellation persistence unconfirmed; retain inputs and query or retry
-32023Conflicting schedule terms for the same semantic submission; recover the original job

Retain wallet reservations while cancellation is lost or uncertain. After acknowledged cancellation, reconcile canonical consumption before releasing local inputs. Resubmission never reactivates cancelled/expired work. Store wallet operation ID, JSON-RPC id, and Broadcaster durable id separately because each serves a different purpose.