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 field | Wire format | Meaning |
|---|---|---|
publishAfter | Decimal-string Unix seconds | Earliest time to begin broadcasting |
executeBefore | Decimal-string Unix seconds | Exclusive end of the broadcast-start window |
cancelTokenHash | Nonzero lowercase 0x bytes32 | Keccak256 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 state | Can it be cancelled? |
|---|---|
scheduled / preparing | Yes, if cancellation wins before durable send reservation |
queued / proving | Only explicitly scheduled jobs without send rights or frozen batch assignment |
pending / submitted / uncertain | No, even when no transaction hash is available yet |
cancelled | Repeating the correct credential is idempotent |
expired / rejected / confirmed / reverted | Cannot 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.
| Error | Action |
|---|---|
-32602 | Fix malformed parameters |
-32020 | Unknown job or invalid credential; deliberately indistinguishable |
-32021 | Too late; continue observing the original job |
-32022 | Cancellation persistence unconfirmed; retain inputs and query or retry |
-32023 | Conflicting 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.