Skip to Content
Symmio Trading-SDK — the SDK surface for builders on Arbitrum
CoreAccountLayerAccount timelocksExecution and delayed fallback

Timelock execution and fallback reference

These low-level AccountLayer APIs accept a root account; resolve a VA with resolveTimelockRootAccount first. All actions import from @symmio/trading-core. Writes return a transaction Hash, not a receipt. Their parameters include normal SDK chain, from, simulation and gasless controls. None automatically retries. Wallet execution rejects a chain mismatch before simulation or broadcast.

An explicitly configured timelockSupported: false produces TIMELOCK_NOT_SUPPORTED before a timelock read, approval request or write. The built-in Base deployment is marked unsupported based on its AccountLayer selector mapping at block 53214315. When an operator verifies a deployment upgrade, override that field in its chain config. An omitted field means unknown; RPC errors are never interpreted as proof that timelocks are unsupported.

encodeInitiateWithdrawCall({ parts, speedUp?, providerData? }): Hex builds the raw Core calldata for scheduling or approval. parts is readonly WithdrawReceiverPart[]; defaults are speedUp: false and providerData: "0x". The encoder does not sign or submit.

Optional authorization on existing writes

allocate, deallocate, initiateWithdraw, addMargin, removeMargin, deleteSubAccount, approveOperationalFee and approveOperationalFeeAllowance accept an optional timelock authorization. Omit it to keep the ordinary write. For a protected selector, provide either { capability, provider, deadline, onApproval? } or { approval }. The provider is injected by the caller; the SDK does not choose a solver.

await addMargin(config, { virtualAccount, amount, timelock: { capability, provider, deadline, onApproval: persistApproval }, });

Each authorization object represents one attempt. If the request times out or the transaction outcome is unknown, reconcile it before deliberately creating another authorization. Automatic retries with the same object do not request or submit again. After issuance, TimelockExecutionError carries the signed approval and exact raw calldata; after submission, getTimelockExecutionRecovery(authorization) also exposes the transaction hash. Persist approvals before submission with onApproval. When a call contains a short-lived Muon signature, reuse the exact original calldata and signature when recovering; a newly fetched signature needs a new approval.

withdraw and withdrawAuto accept a single authorization for an initiate-only withdrawal. A CUSTOM withdrawal accepts { calls: [deallocationAuthorization, withdrawalAuthorization] }, using undefined for an unlocked leg. Each locked leg is independently approved; the two calls remain one atomic transaction. A partial issuance or execution failure raises TimelockBatchExecutionError with the obtained approvals and exact calldata. getTimelockBatchRecovery returns the hash after submission. The helpers reject a separately locked outer _call before requesting approval. Reconcile the receipt before reusing any authorization. executeAccountCalls accepts the same per-call batch authorization for other atomic Core batches.

executeProtectedCall(config, { account, callData, target, timelock, ...writeOptions }) exposes the same flow for any one raw Core or AccountLayer call. Core targets preserve the original account inside _call; AccountLayer calls are passed directly. Its mutation factory is executeProtectedCallMutationOptions(config) and sets retry: false.

executeProtectedFunction(config, { account, target, functionName, args, timelock }) accepts ABI-typed arguments for all 22 documented functions. It encodes the raw call and uses the same explicit approval, execution, and recovery path. Its mutation factory is executeProtectedFunctionMutationOptions(config) and never retries. encodeProtectedFunction({ target, functionName, args }) validates and returns the same raw calldata without signing or submitting. AccountLayer functions must target the selected account as their first argument; the execution helper rejects a mismatch.

const hash = await executeProtectedFunction(config, { account, target: "core", functionName: "allocate", args: [amount18], timelock, });

assertTimelockAuthorizationUnused and assertTimelockBatchUnused reject re-entry before fetching short-lived inputs. The React equivalents include useProtectedCall, useTimelockApprovalProvider and useTimelockSelector.

Core retains the original viem contract error when an unprotected call reverts. The React error normalizer maps a decoded TimelockOpNotApprovedOrScheduled revert to TIMELOCK_REQUIRED and retains the original error as its cause.

For setupTimelocks and clearTimelocks, getTimelockScheduleState derives the window from the longest affected existing selector delay, assuming execution without approvals. Partial approvals can change both ends of that window; re-read the policy and simulate the exact execution before sending it. All reads use one block snapshot. For policy changes requiresSchedule: false means no existing protection needs a schedule; the policy field otherwise identifies the affected selector with the largest delay, not every affected unlocker.

Do not schedule calldata containing a short-lived Muon signature, such as deallocation or margin removal: the signature may expire before the cooldown finishes. Rebuilding that calldata would change its hash and therefore would not match the scheduled operation. matchesScheduledCall(account, rawCallData, innerCallData) checks a direct call or an _call containing exactly that one raw Core call for the original account; useScheduledCallMatch exposes the same check to React consumers.

Writes

FunctionParametersContract effect
setupTimelocksSetupTimelocksParameters: account, unlocker, delay: bigint, selectors: readonly Hex[], optional providerMinimumDelay: bigintSets policy after checking contract/provider minimum. Use setupTimelockPolicy for root resolution, defaults and confirmation.
clearTimelocksClearTimelocksParameters: account, selectorsRemoves those selector policies.
scheduleTimelockOpScheduleTimelockOpParameters: account, callData: HexSchedules keccak256(rawCallData); does not execute withdrawal.
cancelTimelockOpCancelTimelockOpParameters: same fields as scheduleCancels that calldata hash’s schedule; does not cancel an already executed Core withdrawal.
executeTimelockOpExecuteTimelockOpParameters: account, innerCallData: Hex, optional approvals: readonly SignedTimelockApproval[]Executes an AccountLayer call using approvals or a mature schedule.

Every function has signature (config, parameters) → Promise<Hash>. For Core calls use encodeTimelockedCoreCall(originalAccount, rawCoreCall) as innerCallData; for AccountLayer calls pass raw calldata directly. Never schedule the _call wrapper hash when authorizing its inner Core operation.

import { scheduleTimelockOp, getTimelockScheduleState, executeTimelockOp, encodeTimelockedCoreCall, } from "@symmio/trading-core"; const hash = await scheduleTimelockOp(config, { account: root, callData, gasless: false }); const receipt = await config.getClient().waitForTransactionReceipt({ hash }); if (receipt.status !== "success") throw new Error("Schedule reverted"); const state = await getTimelockScheduleState(config, { account: root, callData }); const { timestamp } = await config.getClient().getBlock(); if (state.readyAt !== null && state.expiresAt !== null && timestamp >= state.readyAt && timestamp <= state.expiresAt) { await executeTimelockOp(config, { account: root, innerCallData: encodeTimelockedCoreCall(originalAccount, callData), approvals: [], gasless: false, }); }

Persist the raw calldata and transaction/recovery identity in application storage. Re-read state before execution; contracts remain authoritative if policy or schedule changes after a read. Core cooldown is independent and may require later finalization. A rejection from the solver is not permission to bypass it: fallback selection and reconciliation of unknown requests are explicit consumer decisions.

State and approval reads

FunctionParameters → result
getTimelockSchedule(config, GetTimelockScheduleParameters) with root account, raw callData, optional chainId → Promise<TimelockSchedule>.
getTimelockScheduleGracePeriod(config, { chainId? }?) → Promise<bigint> seconds.
getTimelockScheduleState(config, GetTimelockScheduleStateParameters) → Promise<TimelockScheduleState>. Extends schedule inputs with optional operationCallData for selector lookup, defaulting to callData.
hashTimelockApproval(config, { approval: TimelockApproval, chainId? }) → Promise<Hex>; contract’s canonical approval digest.
isTimelockApprovalUsed(config, { approvalHash: Hex, chainId? }) → Promise<boolean>.

TimelockSchedule is { scheduledAt: bigint, nonce: number } (the nonce is uint32). TimelockScheduleState contains callDataHash, schedule, policy: SelectorTimelock, gracePeriod, readyAt and expiresAt. The last two are bigint | null, null when there is no schedule, otherwise scheduledAt + policy.delay and readyAt + gracePeriod.

TimelockApproval is { account, unlocker, callDataHash, deadline: bigint, salt }. SignedTimelockApproval is { approval: TimelockApproval, signature: Hex }. Check receipt/consumption before reusing an issued approval; expiry or use is not an instruction to issue another automatically.

Query and mutation helpers

getTimelockScheduleStateQueryOptions(config, options: GetTimelockScheduleStateOptions) returns GetTimelockScheduleStateQueryOptions. Options combine required state inputs with standard query overrides. getTimelockScheduleStateQueryKey(options?) returns GetTimelockScheduleStateQueryKey and accepts partial state inputs plus configKey.

These helpers return TanStack mutation options for their corresponding write inputs:

  • setupTimelocksMutationOptions(config)
  • clearTimelocksMutationOptions(config)
  • scheduleTimelockOpMutationOptions(config)
  • cancelTimelockOpMutationOptions(config)
  • executeTimelockOpMutationOptions(config)

All set retry: false, including receipt errors when used by the React wrappers. The React timelock hooks wait for receipts by default and invalidate affected policy, schedule and balance data on confirmation.

Last updated on