Non-custodial signing

Where keys live

The session key is the only thing that can sign, it can only sign what the grant allows, and the grant is on chain where the user can inspect and revoke it without our cooperation. That last clause is what makes it real.

Scope of a grant

A grant is not "this bot may trade". It is a specific, bounded authority, and every bound is independently enforced at signing time even though the chain already checked it.

SessionKeyGrant {
  user:            0xUSER…
  sessionKey:      0xSESS…
  venue:           CTFExchangeV2 @ 0xEXCH…   // exact address, no wildcards
  methods:         [ postOrder, cancelOrder ] // whitelist, see below
  maxNotionalUsd:  5000                       // aggregate over grant lifetime
  maxPerOrderUsd:  500
  collateral:      pUSD @ 0xPUSD…             // exact token, no wildcards
  marketScope:     [ … ]                      // cluster or ≤50 explicit ids
  expiresAt:       now + 30d                  // grants always expire
  revocable:       true                       // always true; never offer otherwise
}

Method whitelist

Grant and revoke

1. Preview. The user is shown the grant in plain English before signing: which venue, which markets, which methods, what ceilings, when it expires. Generated from the grant object so it cannot drift from what is actually requested.
2. Grant. The user signs from their own wallet. This is the only moment their wallet key is used. We never proxy it.
3. Use. The session key signs whitelisted calls within scope. Every signature is logged with the correlation id of the decision that caused it, so any order can be traced back to the rule that proposed it.
4. Revoke. One action, effective immediately, available in the product and independently on chain. Revocation must not require our servers to be up.
5. Expire. Grants expire on their own. A user who walks away is not left with an open-ended authority.

Behaviour on revoke

• In-flight signing attempts fail with SEC_GRANT_REVOKED. They are not retried.
• Open orders are cancelled if cancelOrder is still permitted; otherwise the user is told explicitly which orders remain and how to cancel them directly at the venue.
• Open positions are untouched. We cannot and must not flatten a position without authority — that would itself be custody.
• Every affected user bot moves to paused, with the reason shown.
• The user sees one clear summary of what happened, not a stream of individual failures.

This is the sequence most likely to be got wrong, because the tempting behaviour — "flatten everything to be safe" — is the one that breaks the custody guarantee.

Signature refused mid-run

A signature can be refused for reasons that are not errors: the grant expired, the notional ceiling is reached, the market fell outside scope, the user revoked. A strategy must treat refusal as a normal outcome.

Never retry a refused signature in a loop, and never fall back to a different key. Both patterns turn a bounded authority into an unbounded one.

What we log, and what we must not

• Log: grant creation and revocation, every signature with its correlation id, every refusal with its cause, notional consumed against ceiling.
• Never log: key material, partial key material, signable payloads in a form that could be replayed, or anything that would let a log reader reconstruct authority.