generateGaslessIdempotencyKey
Create the idempotency key for one user action: a random UUID (122 random bits). Save it with the action before the first attempt, and pass it on every attempt of that action.
import { createSubAccounts, generateGaslessIdempotencyKey } from "@symmio/trading-core";
const key = `create-subaccount:${generateGaslessIdempotencyKey()}`;
await pendingActions.save({ key, inputs });
await createSubAccounts(config, { ...inputs, gasless: { account: payer, idempotencyKey: key } });While the service holds a key, it accepts that key at most once — so retrying a write under the same key cannot run the action twice. Every gasless submit takes one: gasless.idempotencyKey on a relayable write, and an idempotencyKey parameter on relayGaslessBatch, relayInstantOperations, relayGrantDelegation, gaslessWalletExecute and both deposit settlements. Without one, the SDK generates a key per call.
Rules for a key
- One key per user action. Reuse it for every attempt of that action — another signer after
GASLESS_SIGNER_NOT_DELEGATED, or “Try again” after a reload. A new action gets a new key, even when its inputs are identical: the service answers a reused key with the old request, possiblysucceeded, so your app would report an outcome for an action that never ran. - Used up once its request ends. After
succeeded,failed,rejectedorreverted, the key keeps returning that result. Trying again is a new action with a new key. - Unique across all users. Keys are global to the deployment, not scoped to a user or signer. A fixed key such as
wallet-exit-1would collide with another user’s action. - Random. A readable prefix of your own is fine (
create-subaccount:<key>). Never build a key only from the action’s inputs: two identical actions would merge into one, and anyone could predict the key. - No secrets or personal data. The service stores the key and returns it in every status response, and it can appear in logs.
- At most 128 characters, and not blank. Anything else throws
GASLESS_IDEMPOTENCY_KEY_INVALIDbefore any prompt.
The full lifecycle — what to save, when a retry is safe, and how to settle an outcome that stays unknown — is in Recovering gasless writes.
Parameters
None.
Returns
stringThrows
Nothing. It reads globalThis.crypto.randomUUID, which every supported runtime provides.