Workflows

Workflow methods compose customer-server operations and preserve the same typed errors, idempotency, deadlines, and cancellation behavior as their underlying resource methods.

Member Payment and Escrow Signing

Member signing starts in @xkova/sdk/member-bff, not a server workflow. Use beginMemberAction and completeMemberAction with an authenticated member session and the exact pending resource. See the member-action walkthrough for application registration, payer setup, fresh authorization, callback handling, and webhook verification. Use the documentation host matching your deployment when validating an unreleased staging build.

Token deploy and mint

tokenDeploy creates an ERC-20, ERC-721, or ERC-1155 token and polls until the token reaches a terminal state. tokenMint submits a mint and polls the token record.

const token = await client.workflows.tokenDeploy(
  'erc721',
  deployRequest,
  {
    idempotencyKey: crypto.randomUUID(),
    poll: { attempts: 30, intervalMs: 2_000 },
  },
);

Off-ramp initiation

offRampInitiate requires the selected chain reference, resolves that chain's burn address, then creates the off-ramp request. It returns before the member's out-of-band burn settles.

const { request, burnAddress } = await client.workflows.offRampInitiate(
  'eip155:43114',
  offRampRequest,
  { idempotencyKey: crypto.randomUUID() },
);

Sandbox wallet funding

client.ramps.fundSandboxWallet creates a normal funding request for dUSDC and preserves the same idempotency, compliance, and settlement behavior as POST /v1/funding-requests. The workspace automatically selects the sandbox conversion partner; callers do not choose a ramp profile.

const request = await client.ramps.fundSandboxWallet(
  {
    account_holder_id: accountHolderId,
    fiat_amount: '100.00',
    fiat: 'USD',
    chain: { kind: 'evm', chain_id: 84532 },
    source_bank_account_id: sourceBankAccountId,
    pool_bank_account_id: poolBankAccountId,
    destination_address: walletAddress,
  },
  { idempotencyKey: crypto.randomUUID() },
);

This method cannot fund Circle Testnet USDC. Acquire issuer-controlled Testnet USDC through Circle's public faucet or a pre-funded wallet, then use its exact chain and contract identity from GET /v1/workspace-tokens.

Cancellation

Pass an AbortSignal to stop a request or poll loop during server shutdown or when the owning application request is cancelled.

const controller = new AbortController();

await client.workflows.tokenMint(tokenId, mintRequest, {
  idempotencyKey: crypto.randomUUID(),
  signal: controller.signal,
});

Production transport

Workflow mutations use the tenant client's bearer API key and the same RFC 9421 request signer as direct resource mutations. A production workflow fails before its first mutation when no signer is configured. Keep one idempotency key for each logical mutation across an explicit retry; every new request invocation receives a fresh nonce and signature. Production reads remain bearer-only.

Signing boundaries

The SDK workflow client does not drive browser signing sessions, accept member keys, or publish purpose-bound signing capabilities. Use the documented hosted or companion member flow for member signing. Customer-server money movement remains available through typed resource methods.

Failure handling

A terminal failed, reverted, cancelled, expired, or rejected status stops polling and throws. Exhausting the configured attempts also throws. Use withRetry only when your application has an explicit retry policy, and reuse the same idempotency key for the same logical write.