Native test vectors — canonical bytes and passkey challenges
Machine-generated by scripts/native-vectors.mts (npx tsx scripts/native-vectors.mts from the repository root) with the
real TypeScript canonical functions of this repository, at commit 52e513b + worktree native-clients. A native client
(Swift) must reproduce canonicalHex and hashHex byte for byte from object.
Each SPW-<DOMAIN>.json is a JSON array of
{ "name": "...", "domain": "SPW-…-v1", "source": "<TS path> <exported function>", "object": { … }, "canonicalHex": "…", "hashHex": "…" }object— the object as JSON, as the API serves it (it went throughJSON.parse(JSON.stringify(…))).canonicalHex— hex of the canonical bytes. Present in every vector of this set.hashHex— hex ofSHA-256(canonical bytes). The WebAuthn challenge is these 32 bytes (base64url, no padding, inoptions.challenge). Exception:SPW-ORDER-INTENT-v1,SPW-ORDER-BODY-v1,SPW-TRADING-MANDATE-v1andSPW-QUOTING-SECTION-v1hashes are never a challenge by themselves (§4).
The generator is deterministic (fixed UUIDs and timestamps, no clock, no randomness, no network, no database query): two runs
give identical files. It asserts for every vector that sha256(canonicalHex) == hashHex where hashHex comes from the real
hash function, and that the bytes start with the domain string.
0. Where canonicalHex comes from
| Case | Domains | How |
|---|---|---|
| The real function returns the bytes | INTENT, NFT-INTENT, NFT-ALLOW, UTXO-LOCKS, MANDATE, VENUE-AUTH, VENUE-ORDER, VENUE-LEVERAGE, VENUE-WITHDRAW, VENUE-MANDATE, VENUE-QUOTING-MANDATE, GMX-AUTH, TRADING-MANDATE, QUOTING-SECTION, ORDER-INTENT, BRIDGE-MINT, BRIDGE-MINT-SOL, BRIDGE-RECLAIM | bytes of the real function, hash of the real function (for the three BRIDGE-* domains the real code has only a bytes function; callers take sha256 of it — services/api/src/bridge.ts:278, signer signer.ts:307) |
| The real function returns only the hash | SOL-TOKEN-ACCOUNT (solTokenAccountHash), ORDER-BODY (orderBodyHashHex) |
bytes rebuilt with the real exported framing canonicalEncode (packages/derivatives/src/live/canonical.ts:26/240) — for ORDER-BODY from the real canonicalOrderFields minus its last three pairs; for SOL-TOKEN-ACCOUNT from the field list of §2.14 — then asserted to hash to the value of the real function |
| JSON-canonical, hash only | RISK-INTENT, GMX-RISK-INTENT, RISK-LIMITS-INTENT, RISK-SWITCH-INTENT, RISK-AUTO-INTENT, TRADING-MANDATE-APPROVAL (canonicalIntentHash, whose stableJson is not exported) |
bytes = domain + "\n" + the exported canonicalJson of services/api/src/trading-api/key-model.ts:30, asserted to hash to the value of the real canonicalIntentHash / riskIntentHash / gmxRiskIntentHash |
| JSON-canonical, real pieces | APIKEY-INTENT | real canonicalJson + real intentChallenge |
| Unexported function | ENROLL (services/api/src/auth.ts:16, not exported) |
hash from the signer's exported copy services/isolated-signer/src/signer.ts:598; bytes = the same string, asserted against it |
Since SHA-256 equality is asserted, a rebuilt canonicalHex is exactly the byte string the real function hashed.
Not generated: none. Every domain of the request could be produced by a real function. The API modules import without a
database (dummy SPW_ORIGIN, SPW_RP_ID, DATABASE_URL, SPW_SIGNER_SECRET; postgres() is lazy and nothing is queried).
Domain strings found in the source and deliberately not covered, because no passkey signs them: SPW-AUDIT-v1
(packages/core/src/audit.ts:16, audit chain) and SPW-CLIENT-ORDER-ID-v1 (packages/trading/src/orders/idempotency.ts:17).
1. The three serializations
1.1 Framed (name, value) pairs — "F"
Used by 21 domains. One implementation, copied in several files (intent.ts:160-171, nft-intent.ts:78, mandate.ts:47-49,
canonical.ts:26, collateral.ts:156, gmx.ts:468, cctp-sol-tx.ts:165); all byte-identical in behaviour.
bytes = UTF8(domain) || 0x00 || for each (name, value) in the FIXED order of the code:
u16 big-endian (byte length of UTF8(name)) || u32 big-endian (byte length of UTF8(value)) || UTF8(name) || UTF8(value)
hash = SHA-256(bytes)- The separator after the domain is one zero byte. No terminator at the end. Lengths are byte lengths of the UTF-8
encoding (vectors with
é,—,«»,°are included), header = 2 + 4 bytes, both big-endian, name length first. - Field order is fixed by the code, never by JSON key order.
- Value stringification (every value is a string before framing):
- string: as is (no trimming, no case change; EIP-55 addresses keep their case).
- integer number (
v,decimals, timestamps, nonces, counts…): decimal digits, no sign, no leading zero, no exponent (String(n)of a safe integer).vis always"1". - boolean:
"1"/"0". - base-unit amounts (
amount,maxFee, gas values…): already decimal strings in the object; framed as is. - decimal string
canon(x)(prices, sizes, USD amounts of the derivatives/trading objects — marked canon below): remove trailing zeros of the fraction, then remove a trailing.; a zero value is"0". The integer part is untouched; never an exponent."2500.50"→"2500.5","25000.000"→"25000","68500.0"→"68500","0.00"→"0","0.0000123400"→"0.00001234". (packages/derivatives/src/decimal.ts:34-73,D.str(D.from(x)).) The object served by the API may or may not already be canonical: always apply it. - null (where the schema allows it): the empty string
""— the pair is still present. - absent optional field: per domain, either the pair is absent, or (only
gmx.orderKey) present with"". Stated per domain below. - lists: per domain — either expanded (
*.count+ indexed names, order kept), or sorted and joined with,. - maps: expanded to one pair per key, keys sorted.
- Sorting is JavaScript's default: by UTF-16 code unit, ascending, no locale. For ASCII this is plain byte order:
digits < upper case <
_< lower case;.< digits. (Vectorsynthetic-x-map-key-sort-order:A, B, a.1, a1, aB, a_1, ab, b.) In Swift:sorted { $0.utf16.lexicographicallyPrecedes($1.utf16) }, neverlocalizedCompare.
1.2 Canonical JSON — "J"
bytes = UTF8(domain + "\n" + J(object)) hash = SHA-256(bytes)J = JSON with object keys sorted at every depth (same UTF-16 code-unit order), no whitespace, arrays in their own
order, and every scalar written as JavaScript's JSON.stringify writes it:
- strings:
"→\",\→\\, U+0008\b, U+0009\t, U+000A\n, U+000C\f, U+000D\r, any other code unit below U+0020 →\u00xx(4 hex digits, lower case); everything else raw UTF-8:/is NOT escaped (Swift'sJSONEncoder/JSONSerializationwrite\/unless.withoutEscapingSlashes), U+007F raw, non-ASCII raw (not\uXXXX), emoji raw; null,true,false;- numbers: integers as plain digits. Non-integers occur in ONE place (
SPW-APIKEY-INTENT-v1limits.*NotionalUsd): the shortest round-trip form of ECMAScript (2500.5,0.1,100000000) — an integer-valued double has no.0. - a key whose value is
undefineddoes not exist in JSON; the object you receive has no such key. (Difference between the two server implementations, not visible on the wire:stableJsonofexec.ts:151would write an explicitundefinedmember asnull,canonicalJsonofkey-model.ts:30drops it. No such member is produced by the code read.)
Vectors release-kill-switch-engaged-by-owner and …-control-chars exercise the escaping rules.
Advice: re-serialize the JSON tree you received (keep integers as integers; do not round-trip amounts through Double).
1.3 Line-joined — "L"
bytes = UTF8(parts joined with "\n") (the domain is the first part; no trailing newline) hash = SHA-256(bytes)2. Signer-verified objects
"Signer" = the isolated signer recomputes the same hash from the object it is sent and verifies the WebAuthn assertion over
it; the API only relays. P = prepare route (issues options.challenge), A = approve route. All routes are POST.
2.1 SPW-INTENT-v1 — F — packages/core/src/intent.ts:145 canonicalBytes, :174 intentHash (field list :109-142)
Order: v, proposalId, keyId, network, chainRef, asset, symbol, decimals, amount, from, to, maxFee, createdAt, expiresAt, policyVersion, then each section only if present in the object, in this order:
evm.nonce, evm.gasLimit, evm.maxFeePerGas, evm.maxPriorityFeePerGasbtc.inputs.count, then per input k = 0… in array orderbtc.inputs.k.txid, btc.inputs.k.vout, btc.inputs.k.value, thenbtc.change, btc.feesol.recentBlockhash, sol.lastValidBlockHeight, sol.createAta(bool),sol.computeUnitLimit, sol.computeUnitPriceswap.provider, swap.toAsset, swap.minOut, swap.router, swap.dataHash, swap.approveGasbridge.provider, bridge.toNetwork, bridge.toDomain, bridge.maxFee, bridge.minFinalityThreshold, bridge.messenger, bridge.transmitter, bridge.approveGas, thenbridge.recipientonly if presentxswap.provider, xswap.toNetwork, xswap.toAsset, xswap.minOut, xswap.limit, xswap.memo, xswap.vault, xswap.vaultPubKey, xswap.router(may be""for a UTXO source — pair present),xswap.expiry, xswap.approveGasvenueDeposit.venue, venueDeposit.venueNetwork, venueDeposit.route, venueDeposit.bridge, venueDeposit.minAmountgmx.venue, gmx.action, gmx.authorizationId, gmx.exchangeRouter, gmx.router, gmx.orderVault, gmx.market, gmx.indexToken, gmx.collateralToken, gmx.orderType, gmx.isLong(bool),gmx.sizeDeltaUsd, gmx.acceptablePrice, gmx.triggerPrice, gmx.executionFee, gmx.approveGas, gmx.orderKey—gmx.orderKeyis always framed:""when absentmemoonly if present (an empty memo""is present: vectortransfer-cosmos-empty-memo) — note: after every section, beforexx.<key>for each key ofxin sorted order (plugin families: xrpl, cosmos, stellar, tron, aptos, sui, near, ton, cardano, polkadot, bch)
No decimal canonicalization here: every amount is a base-unit integer string, framed as is. The function also validates (strict schema; chain section must match the network family; exclusions between sections) — a client only needs the bytes.
Routes (all approved through A = /api/v1/transfers/proposals/:id/approve {assertion} unless said):
| Kind | P | Canonical object in the P response |
|---|---|---|
| transfer | /api/v1/transfers/proposals/:id/request-approval (transfers.ts:181-222) |
intent ({ proposal, intent, options }); hash also at proposal.intentHash |
swap (KyberSwap swap-exec.ts:159, Jupiter swap-exec-sol.ts:275) |
/api/v1/swap/proposals |
NOT returned — { proposal, options } |
bridge (EVM source bridge.ts:250, Solana source bridge-sol.ts:270) |
/api/v1/bridge/proposals |
NOT returned — { proposal, options } |
xswap (xswap.ts:267) |
/api/v1/xswap/proposals |
NOT returned — { proposal, options } |
idempotent replay of the three above (prepare-common.ts:54) |
same routes, same Idempotency-Key |
NOT returned — { proposal, options, replayed: true } |
venueDeposit (derivatives/collateral.ts:343) |
/api/v1/derivatives/live/accounts/:id/collateral/deposit/prepare; A = …/collateral/deposit/:opId/approve |
intent, options (no hash field) |
gmx (derivatives/gmx-exec.ts:567) |
/api/v1/derivatives/gmx/orders, …/gmx/positions/close, …/gmx/orders/:opId/cancel; A = /api/v1/derivatives/gmx/operations/:opId/approve |
intent, options (no hash field) |
For the "NOT returned" rows the proposal view (transfers.ts:39 view) carries intentHash but not the intent, and lacks
keyId, chainRef, createdAt, policyVersion, the evm/sol/btc section, swap.dataHash/router/approveGas,
bridge.toDomain/messenger/transmitter, xswap.memo/vault/expiry: the client cannot rebuild the intent; it can only compare
options.challenge with proposal.intentHash, which proves nothing about what is signed.
Verified by: signer (services/isolated-signer/src/signer.ts:441 sign → intentHash).
2.2 SPW-NFT-INTENT-v1 — F — packages/core/src/nft-intent.ts:95 nftCanonicalBytes, :114 nftIntentHash
Order: v, kind, proposalId, keyId, network, chainRef, standard, asset, quantity, program, from, to, maxFee, createdAt, expiresAt, policyVersion, nftPolicyVersion; then tokenId only if present (after nftPolicyVersion, not next to asset); then if
evm: evm.nonce, evm.gasLimit, evm.maxFeePerGas, evm.maxPriorityFeePerGas; if sol: sol.recentBlockhash, sol.lastValidBlockHeight, sol.computeUnitLimit, sol.computeUnitPrice, then each only if present, in this order:
sol.tokenProgram, sol.createAta (bool), sol.ruleSet, sol.collection. Note sol.createAta is optional here and sits in a
different position than in SPW-INTENT-v1.
P /api/v1/nfts/transfer/prepare → intent, options, hash at proposal.intentHash; A /api/v1/nfts/transfer/:id/approve.
Verified by: signer (services/isolated-signer/src/nft.ts:54).
2.3 SPW-NFT-ALLOW-v1 — F — nft-intent.ts:162 nftAllowBytes, :167 nftAllowHash
Order: v, kind, requestId, keyId, network, action, address, createdAt, expiresAt, policyVersion.
P /api/v1/nfts/allow/prepare → intent, options (no hash field); A /api/v1/nfts/allow/approve {intent, assertion} (the
client sends the intent back). Signer: nft.ts:157.
2.4 SPW-UTXO-LOCKS-v1 — F — nft-intent.ts:135 utxoLockBytes, :144 utxoLockHash
Order: v, kind, requestId, keyId, network, action, reason, outpoints.count, per outpoint k in array order (not sorted)
outpoints.k.txid, outpoints.k.vout, then createdAt, expiresAt, policyVersion.
P /api/v1/utxo-locks/prepare → intent, hash, options; A /api/v1/utxo-locks/approve {intent, assertion}. Signer: nft.ts:131.
2.5 SPW-MANDATE-v1 (spot agent vault mandate) — F — packages/core/src/mandate.ts:41 mandateBytes, :52 mandateHash
Order: v, mandateId, keyId, vaultIndex, vault, network, provider, assets (= asset ids sorted, joined with ,), then
maxOrder.<assetId> for each key of maxOrder sorted, then maxDaily.<assetId> for each key of maxDaily sorted, then
maxOrdersPerDay, maxSlippageBps, createdAt, expiresAt, strategySha256, label. Asset ids keep their case (0x8335… sorts
before native). The key sets of the two maps may be smaller than assets.
P /api/v1/agents/:id/mandate/prepare → mandate, hash, options (agents/mandate-write.ts:47-50); A
/api/v1/agents/:id/mandate/approve. Signer: signer.ts:141.
2.6 SPW-VENUE-AUTH-v1 — F — packages/derivatives/src/live/canonical.ts:87 venueAuthorizationBytes, :98
Order: v, authorizationId, keyId, venue, network, account, agentAddress, agentName, mode, policy.allowedInstruments (sorted,
,-joined), policy.maxLeverage, policy.maxOrderNotional (canon), policy.maxPositionNotional (canon),
policy.maxGrossExposure (canon), policy.maxOrdersPerDay, policy.maxPriceDeviationBps, createdAt, expiresAt, approveNonce, ackSha256.
P /api/v1/derivatives/live/accounts/:id/authorization/prepare → authorization, hash, options; A
…/authorization/approve {assertion, acknowledged: true}. Signer: venue.ts:62.
2.7 SPW-VENUE-ORDER-v1 — F — canonical.ts:150 venueOrderBytes, :159
Order: v, authorizationId, venue, network, account, kind, instrument, side, type, size (canon), price (canon),
triggerPrice ("" when null, else canon), reduceOnly (bool), tif, clientId, nonce, expiresAt — nonce/expiresAt
are unix milliseconds and come last although they are declared first in the schema.
P /api/v1/derivatives/live/accounts/:id/orders and …/accounts/:id/close → canonical (also order.canonical), hash,
options (null when not approvable); A …/orders/:clientId/approve. Signer: venue.ts:205.
2.8 SPW-VENUE-LEVERAGE-v1 — F — canonical.ts:170 venueLeverageBytes, :177
Order: v, authorizationId, venue, network, account, kind, instrument, leverage, marginMode, nonce, expiresAt.
P /api/v1/derivatives/live/accounts/:id/leverage → canonical, hash, options; A …/leverage/:actionId/approve. Signer: venue.ts:221.
2.9 SPW-VENUE-WITHDRAW-v1 — F — packages/derivatives/src/live/collateral.ts:150 venueWithdrawalBytes, :168
Order: v, withdrawalId, keyId, venue, network, account, destination, amount (canon), fee (canon), time (ms),
createdAt, expiresAt (seconds).
P /api/v1/derivatives/live/accounts/:id/collateral/withdraw/prepare → withdrawal, hash, options; A
…/collateral/withdraw/:opId/approve. Signer: venue-collateral.ts:53.
2.10 SPW-VENUE-MANDATE-v1 (derivative mandate) — F — packages/derivatives/src/live/mandate.ts:71 venueMandateBytes, :82
Order: v, mandateId, authorizationId, keyId, venue, network, account, agentAddress, strategySha256, agentId, instruments, maxOrderNotional (canon), maxGrossExposure (canon), maxOrdersPerDay, maxOrdersPerHour, maxDailyTurnover (canon),
floorEquity (canon), maxPriceDeviationBps, createdAt, expiresAt, ackSha256.
instruments = ONE value: the entries sorted by instrument, each written instrument|maxLeverage|canon(maxPositionNotional), joined with ,.
P, three ways: (a) /api/v1/derivatives/live/accounts/:id/mandate/prepare → mandate, hash, options; (b)
/api/v1/mandates/:id/approve/prepare → signer.mandate, signer.hash, signer.options; (c)
/api/v1/agents/:id/perp/live/prepare → mandate, hash, options. A: (a) …/mandate/approve {assertion, acknowledged};
(b) /api/v1/mandates/:id/approve {assertion, bindingAssertion, acknowledged}; (c) /api/v1/agents/:id/perp/live/approve.
Signer: venue-mandate.ts:59.
2.11 SPW-VENUE-QUOTING-MANDATE-v1 — F — packages/derivatives/src/live/quoting.ts:93 venueQuotingMandateBytes, :106
Order: v, mandateId, authorizationId, keyId, venue, network, account, agentAddress, strategySha256, agentId, instruments, maxRestingTotal, maxGrossExposure (canon), minHalfSpreadBps, maxDistanceBps, maxReduceDeviationBps, floorEquity (canon),
rate.burstActions, rate.actionsPerMinute, rate.ordersPerHour, rate.ordersPerDay, rate.dailyTurnover (canon),
deadManSeconds, createdAt, expiresAt, ackSha256.
instruments = entries sorted by instrument, each
instrument|maxLeverage|canon(maxQuoteNotional)|maxRestingPerSide|canon(maxRestingNotionalPerSide)|canon(maxInventoryNotional), joined with ,.
P /api/v1/mandates/:id/approve/prepare (quoting branch, mandates/service.ts:372-379) → signer.mandate, signer.hash
(also hashes.signerMandate), signer.options; A /api/v1/mandates/:id/approve (assertion). Signer: venue-quoting.ts:81.
2.12 SPW-GMX-AUTH-v1 — F — packages/derivatives/src/live/gmx.ts:460 gmxAuthorizationBytes, :474
Order: v, authorizationId, keyId, venue, network, account, mode, contracts, exchangeRouter, policy.allowedMarkets (sorted,
,-joined — case-sensitive sort of EIP-55 addresses: upper-case hex letters sort before lower-case), policy.maxLeverage, policy.maxOrderSizeUsd (canon), policy.maxOrdersPerDay, policy.maxPriceDeviationBps, policy.maxExecutionFeeWei, createdAt, expiresAt, ackSha256.
P /api/v1/derivatives/gmx/authorization/prepare → authorization, hash, options; A
…/gmx/authorization/approve {authorization, assertion} (the client sends it back). Signer: venue-gmx.ts:40.
2.13 CCTP second legs — L
| Domain | Function | Parts, joined with \n |
|---|---|---|
SPW-BRIDGE-MINT-v1 |
packages/core/src/cctp.ts:284 cctpMintRetryBytes(proposalId, messageHash, gas) |
domain, proposalId, messageHash, gas.nonce, gas.gasLimit, gas.maxFeePerGas, gas.maxPriorityFeePerGas |
SPW-BRIDGE-MINT-SOL-v1 |
packages/core/src/cctp-sol-tx.ts:141 cctpSolMintRetryBytes(proposalId, messageHash, sol) |
domain, proposalId, messageHash, sol.recentBlockhash, sol.lastValidBlockHeight, sol.computeUnitLimit, sol.computeUnitPrice |
SPW-BRIDGE-RECLAIM-v1 |
cctp-sol-tx.ts:144 cctpSolReclaimBytes(proposalId, eventAccount, messageHash, sol) |
domain, proposalId, eventAccount, messageHash, then the same four sol values |
messageHash is the string the server holds (0x + 64 hex, as returned by cctpMessageHash). The vector object is
{ proposalId, messageHash, gas | sol [, eventAccount] } — the arguments by name; it is not an object any route serves.
- MINT / MINT-SOL: P
/api/v1/bridge/proposals/:id/retry-mint/options→{ proposal, options }: NOT returned (neithermessageHashnor the gas / budget; onlyproposal.id). A/api/v1/bridge/proposals/:id/retry-mint. Signer:signer.ts:307/:340. - RECLAIM: P
/api/v1/bridge/proposals/:id/reclaim/options→{ proposal, options, deposit, networkFee }: NOT returned (proposal.bridge.sol.eventAccountis there;messageHashand the budget are not). A…/reclaim. Signer:signer.ts:377.
2.14 SPW-SOL-TOKEN-ACCOUNT-v1 — F — packages/core/src/cctp-sol-tx.ts:160 solTokenAccountHash (hash only)
Order: v, requestId, keyId, network, chainRef, owner, mint, tokenAccount, maxFee, createdAt, expiresAt, policyVersion, sol.recentBlockhash, sol.lastValidBlockHeight, sol.computeUnitLimit, sol.computeUnitPrice.
P /api/v1/bridge/solana/token-account/options (bridge-sol.ts:514-541) → { requestId, owner, tokenAccount, rent, rentDisplay, networkFee, networkFeeDisplay, symbol, expiresAt, options }: NOT returned (missing keyId, chainRef, mint, maxFee
= networkFee + the fixed rent bound, createdAt = expiresAt − 50, policyVersion, the whole sol section). A
/api/v1/bridge/solana/token-account {requestId, assertion}. Signer: signer.ts:393.
2.15 SPW-ENROLL-v1 — L — services/api/src/auth.ts:16 enrollChallenge (not exported); signer copy services/isolated-signer/src/signer.ts:598
SHA-256("SPW-ENROLL-v1\n" + credentialId + "\n" + publicKey) — credentialId = the WebAuthn credential id (base64url, no
padding), publicKey = base64url (no padding) of the credential public key bytes as @simplewebauthn/server returns them at
registration (COSE key; auth.ts:83). The vector object is { credentialId, publicKey } (argument names, not a served object).
P /api/v1/security/devices/verify → { pendingId, options }: partly returned — pendingId is the credential id, the
publicKey string is not served; the new device holds its own public key from its registration response (that those bytes are
the same COSE encoding was not verified here). A /api/v1/security/devices/confirm {pendingId, assertion}. Signer:
signer.ts:122 → :598.
3. API-only objects (the signer never sees them) — J
Verified by the API alone against its own credentials table (auth.ts:44 verifyOwnerAssertion; API keys:
verifyAuthenticationResponse in trading-api/keys.ts:126-134). They guard against a stolen session; nothing is signed on
their strength. All are domain + "\n" + J(intent); hash function services/api/src/derivatives/exec.ts:154
canonicalIntentHash (stableJson :151) except API keys. Every intent built by risk/passkey.ts:27 prepareIntent is the
body plus nonce (UUID), createdAt, expiresAt (unix ms, TTL 300 000).
| Domain | Built at | Intent members (before sorting) | P → A | P response |
|---|---|---|---|---|
SPW-RISK-INTENT-v1 |
exec.ts:155 riskIntentHash, :579-600 prepareRisk |
v, kind ('policy'|'resume'|'rebase'), accountId, venue, network, account, authorizationId, policy (object|null), loosened[], subject (string|null), nonce, createdAt, expiresAt |
/api/v1/derivatives/live/accounts/:id/policy/prepare, …/resume/prepare, …/rebase/prepare → …/policy/approve, …/resume, …/rebase |
{ needed, kind, loosened, **intent**, hash, options, expiresAt } (all null when needed: false) |
SPW-GMX-RISK-INTENT-v1 |
derivatives/gmx-exec.ts:118 gmxRiskIntentHash |
v, kind ('gmx-limits'|'gmx-resume'), authorizationId, limits ({maxDailyLoss, maxTotalLoss}|null), loosened[], subject, nonce, createdAt, expiresAt |
/api/v1/derivatives/gmx/limits/prepare, …/gmx/resume/prepare → …/gmx/limits/approve, …/gmx/resume |
intent, hash, options |
SPW-RISK-SWITCH-INTENT-v1 |
risk/service.ts:174 |
v, kind ('kill_switch'|'read_only'), engagedAt (ms|null), engagedBy ("<kind>:<id>"|null), reason (string|null) + stamp |
/api/v1/risk/kill-switch/release/prepare, /api/v1/risk/read-only/release/prepare → …/release |
{ needed, kind, **intent**, hash, options, expiresAt } |
SPW-RISK-LIMITS-INTENT-v1 |
risk/service.ts:244 |
v, kind: 'limits', mode ('paper'|'live'), limits (RiskLimits, packages/trading/src/risk/engine.ts:81; absent members are absent), loosened[] + stamp |
/api/v1/risk/limits/:mode/prepare → /api/v1/risk/limits/:mode/approve |
{ needed, loosened, **intent**, hash, options, expiresAt } |
SPW-RISK-AUTO-INTENT-v1 |
risk/service.ts:271 |
v, kind: 'auto', auto ({totalLoss, drawdown, dailyLoss} booleans), loosened[] + stamp |
/api/v1/risk/auto/prepare → /api/v1/risk/auto {auto, assertion} |
same shape |
SPW-TRADING-MANDATE-APPROVAL-v1 |
mandates/service.ts:71, :351 (directional), :374 (quoting) |
v, kind: 'trading_mandate_approval', mandateId, tradingMandateHash, principal ("<kind>:<id>"), mode: 'live', signer {shape, mandateHash}, [quotingSectionHash — quoting only, otherwise the key is absent] + stamp |
/api/v1/mandates/:id/approve/prepare (also surfaced as binding by /api/v1/agents/:id/perp/live/prepare) → /api/v1/mandates/:id/approve, field bindingAssertion |
binding.intent, binding.hash, binding.options, binding.domain, binding.expiresAt |
SPW-APIKEY-INTENT-v1 |
trading-api/key-model.ts:30 canonicalJson, :38 intentChallenge; trading-api/keys.ts:76 storeIntent |
v, action, intentId, origin, preparedAt (ISO string) + create: key {id, name, scopes[], expiresAt (ISO), limits {maxOrderNotionalUsd, maxDailyNotionalUsd: number|null}, restrictions {networks[], venues[], instruments[], ipAllow[]}, rateLimitPerMin, mandateId|null}; rotate: keyId, newKeyId; update: keyId, changes{…}, widening[] |
/api/v1/developer/keys/prepare, …/keys/:id/rotate/prepare, …/keys/:id/update/prepare → /api/v1/developer/keys, …/keys/:id/rotate, …/keys/:id/update {intentId, assertion} |
{ intentId, **intent**, sha256, expiresAt, options } — the hash field is sha256, not hash |
A live trading-mandate approval is two passkey ceremonies in one request: assertion over the signer shape
(§2.10 / §2.11, verified by the signer) and bindingAssertion over the approval intent (API only). The binding assertion is
stored and verified again on each load (risk/passkey.ts:62).
4. Hashes that are embedded, never a challenge by themselves — F
| Domain | Function | Order | Where it goes |
|---|---|---|---|
SPW-TRADING-MANDATE-v1 |
packages/trading/src/mandate/trading-mandate.ts:97 tradingMandateBytes, :111 |
v, mandateId, principal.kind, principal.id, accounts, venues, networks, instruments, marketKinds, orderTypes (each of these six: sorted, ,-joined), maxCapitalUsd, maxOrderNotionalUsd, maxPositionNotionalUsd, maxLeverage, maxDailyLossUsd, floorEquityUsd (all canon), createdAt, notBefore, notAfter, frequency.perMinute, frequency.perHour, frequency.perDay, maxSlippageBps, maxFeeUsd (canon), stopConditions (sorted, ,-joined), mode, strategySha256 ("" when null), label |
tradingMandateHash of the approval intent (§3) and of the quoting section. Served as mandate + hash by /api/v1/mandates/:id/approve/prepare, as tradingMandate.mandate / .hash by the perp live prepare |
SPW-QUOTING-SECTION-v1 |
packages/trading/src/mandate/quoting-mandate.ts:233 quotingSectionBytes, :245 |
v, mandateId, tradingMandateHash, terms.levelsPerSide, terms.minHalfSpreadBps, terms.maxDistanceBps, terms.burstActions, terms.actionsPerMinute, terms.quotesPerHour, terms.quotesPerDay, terms.dailyTurnoverUsd (canon), terms.deadManSeconds, engine.policy, engine.configSha256, engine.quoteSizeUsd, engine.softInventoryUsd, engine.hardInventoryUsd (canon ×3), engine.maxSessionMinutes, engine.hours ("<start>-<end>", "" when null), engine.maxSessionLossUsd (canon), engine.stopBeforeExpiryS, engine.breakers (keys sorted, code=action, ,-joined; "" when empty), engine.flattenOnStop (bool) |
quotingSectionHash of the approval intent. Served as quoting.section / quoting.hash (also hashes.quotingSection) |
SPW-ORDER-INTENT-v1 |
packages/trading/src/orders/canonical.ts:119 canonicalOrderBytes, :120; fields :105-118 |
v, venue, network, instrument, marketKind, side, type, size, notional, limitPrice, triggerPrice (each canon, "" when null), reduceOnly (bool), tif, maxSlippageBps, maxFeeUsd (canon), leverage (canon / ""), marginMode ("" when null), mode, principal.kind, principal.id, mandateId ("" when null), clientOrderId, createdAt, expiresAt (ms) |
order identity (orderHash); returned as {order, hash} by order previews. No generateAuthenticationOptions site uses it: a live Hyperliquid order is approved over SPW-VENUE-ORDER-v1 |
SPW-ORDER-BODY-v1 |
orders/canonical.ts:129 orderBodyHashHex (hash only) |
the same list without the last three (clientOrderId, createdAt, expiresAt), under the other domain |
idempotency comparison only |
Element formats of the sorted lists of a trading mandate: account = vault|<network>|<vaultIndex>|<address> or
venue_account|<venue>|<network>|<account>; stop condition = loss_gte|canon(usd), drawdown_gte|<bps>,
consecutive_rejects_gte|<count>, data_stale_gte|<ms>, signer_unreachable_gte|<ms> (trading-mandate.ts:92-93). The
lists are sorted after formatting.
5. One domain string, several meanings — read this before grepping
SPW-INTENT-v1is serialized in exactly ONE place:packages/core/src/intent.ts:105/160. Its occurrence inpackages/core/src/nft-intent.ts:7is a comment ("the transfer intent … is not touched"). NFT objects have their own domains and their own field lists; only the framing is shared.SPW-MANDATE-v1is serialized in exactly ONE place:packages/core/src/mandate.ts:47(the spot vault mandate). Every other occurrence is a label, not a serialization:packages/trading/src/mandate/trading-mandate.ts:6(comment),:333,:336,:460,:504,:624(the value of ashapetag / a table of signer shapes),services/api/src/agents/mandate-write.ts:3andagents/runtime-routes.ts:54(comment / shape tag).SPW-VENUE-MANDATE-v1: one serialization (derivatives/src/live/mandate.ts:73); elsewhere ashapetag — including the string valuesigner.shapeINSIDE theSPW-TRADING-MANDATE-APPROVAL-v1intent, where it is hashed as data.SPW-VENUE-QUOTING-MANDATE-v1,SPW-TRADING-MANDATE-v1,SPW-QUOTING-SECTION-v1: one serialization each; the other occurrences are constants, shape tags, comments or SQL comments (services/api/src/db.ts).SPW-ORDER-INTENT-v1also appears inservices/api/src/trading-api/spec.ts:166and the generated SDK (packages/trading-sdk/src/generated/openapi.ts:102) as documentation text.SPW-ENROLL-v1: two independent copies of the same one-liner (APIauth.ts:16, signersigner.ts:598).- Two JSON canonicalizers share the "J" format:
stableJson(exec.ts:151, private) andcanonicalJson(key-model.ts:30; a third private copy inagent-runtime/model.ts:192, a client copy inpackages/trading-sdk/src/util.ts:10). They agree on every value that can travel as JSON. - Seconds vs milliseconds: intents, NFT objects, mandates, authorizations use unix seconds for
createdAt/expiresAt;SPW-VENUE-ORDER/LEVERAGEnonce/expiresAt,approveNonce,VenueWithdrawal.time, canonical orders and every "J" intent stamp use milliseconds. Irrelevant for the bytes (digits either way), relevant for display.
6. Routes that do NOT return the full canonical object to the client
POST /api/v1/swap/proposals(KyberSwap and Jupiter) —SPW-INTENT-v1POST /api/v1/bridge/proposals(EVM source and Solana source) —SPW-INTENT-v1POST /api/v1/xswap/proposals—SPW-INTENT-v1- any idempotent replay of 1–3 (
prepare-common.tschallengeFor:{ proposal, options, replayed }) POST /api/v1/bridge/proposals/:id/retry-mint/options—SPW-BRIDGE-MINT-v1andSPW-BRIDGE-MINT-SOL-v1POST /api/v1/bridge/proposals/:id/reclaim/options—SPW-BRIDGE-RECLAIM-v1POST /api/v1/bridge/solana/token-account/options—SPW-SOL-TOKEN-ACCOUNT-v1POST /api/v1/security/devices/verify—SPW-ENROLL-v1(credential id returned aspendingId,publicKeynot)
On these routes a native client cannot recompute the challenge; it signs what the server (and then the signer) says. Every other prepare route of §2–§3 returns the complete object.
7. How this document was checked
- Run: the generator twice → identical files (SHA-256 of all 28 files compared); both output directories identical.
- Run: an independent Python recomputation written from the prose of this file (not from the TypeScript) reproduces
canonicalHexandhashHexof 52 vectors: all 22SPW-INTENT-v1, bothSPW-VENUE-AUTH-v1, all 3SPW-TRADING-MANDATE-v1, all 20 "J" vectors (7 domains),SPW-BRIDGE-RECLAIM-v1, bothSPW-BRIDGE-MINT-v1, bothSPW-ENROLL-v1. - Read, not run: the route table (paths, response field names, which component verifies). It was established by reading
services/api/srcandservices/isolated-signer/src; no server was started. Not read: the exact shape ofGET /api/v1/mandates/:idand the routes that call the order previews. - The vectors are schema-valid examples, not transactions: addresses, hashes and block hashes are placeholders (the
canonical functions validate shape, not chain state).
synthetic-x-map-key-sort-orderis a sort-order probe that no plugin would produce; the three BRIDGE-* and the ENROLLobjects are argument lists, not served objects.