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
| Function | Parameters | Contract effect |
|---|---|---|
setupTimelocks | SetupTimelocksParameters: account, unlocker, delay: bigint, selectors: readonly Hex[], optional providerMinimumDelay: bigint | Sets policy after checking contract/provider minimum. Use setupTimelockPolicy for root resolution, defaults and confirmation. |
clearTimelocks | ClearTimelocksParameters: account, selectors | Removes those selector policies. |
scheduleTimelockOp | ScheduleTimelockOpParameters: account, callData: Hex | Schedules keccak256(rawCallData); does not execute withdrawal. |
cancelTimelockOp | CancelTimelockOpParameters: same fields as schedule | Cancels that calldata hash’s schedule; does not cancel an already executed Core withdrawal. |
executeTimelockOp | ExecuteTimelockOpParameters: 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
| Function | Parameters → 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.