DOCS / REFERENCE / AUTHORIZATION MODEL
Authorization model
COPIED FROM chimpdao-contracts/docs/AUTH.md · REVISION 6fd752349933
·
Repository ↗
How chip signatures authorize state changes. Shared crypto lives in
contracts/chip-auth/.
Two models, differing in what the chip proves:
| Chip is… | Mechanism | Contracts | |
|---|---|---|---|
| Account auth | the account’s key | CustomAccountInterface; the host builds the payload |
pocket, account |
| Presence attestation | a second factor beside a wallet | call_digest over the specific call |
nfc-nft, examples/prize |
Both bind the call; neither accepts an opaque blob.
Account auth: Pocket and the Chimp account
Both implement __check_auth and sign the same thing, the payload the host computes:
sha256(HashIdPreimage::SorobanAuthorization {
network_id, nonce, signature_expiration_ledger, invocation
})
invocation is the contract, function name, argument ScVals and sub-invocations being
executed. Change the destination or amount and the digest changes. The host enforces replay and
expiry, so Pocket keeps no nonce.
CAP-71 added the credential variant sorobanCredentialsAddressV2, whose preimage also
carries the authorizing address. The contract sees only the resulting 32-byte payload; the
client must sign the right one (Digest / replay matrix).
- No Pocket
transferentry point. A payment is a plain SACtransfer(pocket, merchant, amount)that the host routes to Pocket’s__check_auth, so the purse works with Blend or any contract without new code. - Every Pocket decision is chip-gated,
set_ownerincluded: it callsrequire_authon the contract’s own address, which routes to__check_authand binds that call’s arguments. The one exception,apply_upgrade_policy, only carries out a decision the chip already signed.sweepdoes not exist, soowneris a signpost the card rewrites and there is no path to the float without the chip. A lost card is lost money. - Pocket verifies inline. It stores the card’s
Curveand callschimpdao_chip_auth::verify_chip_authdirectly. No stored verifier address can be re-pointed, no registry outage can freeze a purse, and__check_authhas no re-entrancy surface.
The signature binds the call because an unbound one is a bearer credential. A signature
over an opaque message would tie nothing on chain to token, to or amount, so one
(message, auth, nonce) would authorize any transfer of any amount anywhere. A transaction
envelope is flooded across the overlay before ledger close, and a transfer that fails leaves
its authorization readable on the ledger with its nonce unconsumed. The host payload names the
exact invocation, so a leaked entry authorizes only that call, until its expiration ledger.
pocket/src/test.rs pins the binding with a software chip, natively and as built:
a_purse_accepts_its_own_chip_on_either_curve, a_purse_refuses_another_card_and_a_signature_over_another_call and
a_junk_signature_is_an_invalid_signature.
The Chimp account: same payload, different envelope
A purse is bound to one card, so its envelope carries only the signature. An account holds a set of signers, cards and passkeys, so the envelope also names which one signed and says how:
pub struct CardSigner { pub key: BytesN<65>, pub curve: Curve } // stored, per card
pub struct PasskeySigner { pub key: BytesN<65>, pub credential_id: Bytes,
pub rp_id_hash: BytesN<32> } // stored, per passkey
pub struct AccountAuth { pub key: BytesN<65>, pub auth: AccountProof } // presented per call
pub enum AccountProof { <a card proof>, Webauthn(WebauthnAuth) }
__check_auth looks key up in the set the proof’s kind names, Cards for a card proof,
Passkeys for Webauthn, never both, and verifies the proof against that stored
entry, so naming someone else’s key buys nothing and a key listed as a card is never accepted as
a passkey, nor the reverse. A card client builds the same XDR whether or not it knows passkeys
exist.
auth_contexts is ignored. Any signer may authorize any context (that is 1-of-n), and not
matching on Context keeps the contract indifferent to the variants CAP-85 added. A card and a
passkey have exactly the same power. Nothing is hashed on top of the host payload; the account
verifies signature_payload as delivered.
Signer management (add_card, remove_card, add_passkey, remove_passkey, abandon) and
code changes (upgrade, update, set_upgrade_policy, set_factory) are authorized by the
account itself, which routes back through __check_auth, so “an existing signer consents” and
“the account authorized it” are the same statement. remove_card and remove_passkey refuse the
last signer of either kind (LastSigner, #504), since an account with no signer can never
authorize anything again, including adding one. abandon() empties an account deliberately.
contracts/account/src/test.rs (the wire tests, with the cards’ constants and
TERMINAL_ACCOUNT_AUTH_WEBAUTHN, TERMINAL_PASSKEY_SIGNER,
TERMINAL_VEC_PASSKEYS) decode real client XDR to pin the exact bytes a client builds. Nothing
else catches field-order or variant-name drift across repos.
Passkeys (WebAuthn)
A passkey is a P-256 key held by a platform authenticator or a security key. It is verified with the host
primitive secp256r1_verify, plus a wrapper: an authenticator signs
authenticator_data ‖ sha256(client_data_json), and the browser puts the challenge into
client_data_json. The challenge is the host’s signature_payload. verify_webauthn (chip-auth) checks exactly
this, then the signature:
authenticator_datais 37 to 512 bytes and its first 32 bytes equal the signer’s storedrp_id_hash.- The flags byte has user presence (
0x01) and user verification (0x04) both set. client_data_jsonis at most 1024 bytes and starts with the exact bytes{"type":"webauthn.get","challenge":", thenbase64url(signature_payload)(43 characters, no padding), then". The payload is encoded and compared as bytes: no JSON parser, no substring search, no base64 decoding.secp256r1_verify(key, sha256(authenticator_data ‖ sha256(client_data_json)), signature)withsignatureas raw 64-byter ‖ s.
Structural failures (1 to 3) make __check_auth return InvalidSignature (#502). A signature
that does not verify, or one with a high s, traps, because secp256r1_verify has no
fallible form; the client converts an authenticator’s DER signature to raw r ‖ s and
normalises s to the lower half of the curve order.
Deliberately not checked: origin and crossOrigin. The relying-party id is chimpdao.xyz for
the whole domain, so the landing site, the NFT viewer and a future web app can each ask for a
passkey signature; that is safe only while every host under the domain is ChimpDAO’s
(CLIENT-INTEGRATION.md § 5.1). Also not checked: the signature counter
(synced passkeys report 0 forever), backup flags, attestation and extensions. The serialisation
order of client_data_json is fixed by the WebAuthn specification, so a client that orders the
fields differently fails closed; the_pinned_assertion_verifies_for_an_account_built_from_the_pinned_signer pins a vector.
credential_id is not trusted: it only lets a client find which stored key to present. The
relying-party id is part of the stored signer, so adding a passkey for a different relying party
is an explicit, signed add_passkey.
Pocket vs account
sequenceDiagram
participant Chip
participant Host as Soroban host
participant Pocket
participant Account as Chimp account
Note over Host: payload = hash of contract, function, args, nonce, expiry
Chip-->>Host: signature over the payload (signed before submission)
Note over Host,Pocket: Pocket spend
Host->>Pocket: __check_auth(payload, ChipAuth, contexts)
Pocket->>Pocket: verify_chip_auth(payload, stored Chip, stored Curve)
Note over Host,Account: Account spend, card
Host->>Account: __check_auth(payload, AccountAuth, contexts)
Account->>Account: find the named key in Cards
Account->>Account: verify_chip_auth(payload, that card's key and curve)
Note over Host,Account: Account spend, passkey
Host->>Account: __check_auth(payload, AccountAuth{Webauthn}, contexts)
Account->>Account: find the named key in Passkeys
Account->>Account: verify_webauthn(payload, its rp_id_hash, its key, assertion)
They differ only in how the signer is found: a purse has one card in storage; an account has two sets and the envelope names one signer and its kind. Each then runs a linked verification over the same host payload, and the host owns binding, replay and expiry. Do not add an app nonce to either.
Presence attestation: nfc-nft
The wallet authorizes through its own Soroban auth, and the chip separately proves the physical
object was on the reader. nfc-nft verifies that itself:
digest = sha256(domain ‖ contract_xdr ‖ fn_name_xdr ‖ args_xdr ‖ nonce_xdr)
Built by call_digest. Every attested field is inside
the hash, so an attestation is good for one call to one function of one contract with one set of
arguments, once. domain is per contract family (chimpdao.nfc-nft.v3, chimpdao.prize.v1)
and its suffix is bumped whenever the digest construction changes.
verify_for_card(public_key, digest, auth) is public but stateless: it returns a bool over the
registry’s stored key and curve and never produces a signature. Replay is the caller’s problem;
integrators bring their own domain and nonce (examples/prize).
Verification is linked, not delegated
There are no verifier contracts. chimpdao-chip-auth is an rlib implementing both algorithms
once; pocket, account and nfc-nft link it and call verify_chip_auth directly. The
account’s WebAuthn check is a module of the account itself and is linked the same way.
A verifier reached through a stored contract address is a pointer someone can re-aim, and every
purse’s liveness would hang on the contract behind it. Linking removes both: a purse’s
__check_auth reads only its own storage. The cost is that a crypto fix is a fleet upgrade
rather than one contract, which is what UpgradePolicy is for; the crypto is ~1–2 KB of wasm.
nfc-nft.verify_for_card serves integrators: an outside contract links the rlib only for
call_digest (a hash) and cross-calls verify_for_card for the crypto.
Auth matrix
| Entry | Wallet require_auth |
Chip | Notes |
|---|---|---|---|
nfc mint |
admin | attestation over [pubkey, curve, upgrade_policy, uri] |
provisions the trio: records curve and pubkey↔token, deploys the purse, writes Owner once. The destination is derived, so the attestation is the whole holder-side authorization. See ARCHITECTURE.md |
nfc set_factory |
admin | — | names the factory mint deploys through; mint refuses without it (#106) |
nfc clawback |
admin | — | central escape hatch; emits transfer (purse → admin). The chip stays registered, so it cannot be minted again, and its purse stays where it is |
nfc, collection, factory set_admin |
admin | — | hands the role over at once, no second step; emits SEP-41 set_admin |
nfc set_trait / set_trait_metadata_uri |
admin | — | ERC-7496; tier is the only trait; set_trait emits set_trait and metadata |
nfc pocket / curve / trait_value(s) / verify_for_card and the token views |
— | — | public views |
Pocket: any call it authorizes (SAC transfer, vault deposit, pool submit) |
— | __check_auth |
the chip is the account |
Pocket set_owner |
— | __check_auth |
repoints the signpost when the card changes root |
Pocket set_upgrade_policy |
— | __check_auth |
the decision to join or leave the fleet |
Pocket apply_upgrade_policy |
— | — | permissionless: only makes the executable match a choice the chip already signed. Single-shot: refuses (#405) unless a chip-signed decision is pending. Emits apply_upgrade_policy |
Pocket upgrade |
— | __check_auth |
Manual only; refuses under Managed (#403) |
router batch |
caller → that address’s __check_auth (purse or account) |
— | pass-through: no admin, no upgrade path, no state. Anchors every leg into one condensed tree: one entry, one nonce, one tap. A move between two of the holder’s balances adds a second, non-root entry for the destination, discovered with record_allow_nonroot for an account and declared as a cosigner tree for a purse. A non-root entry authorizes its own invocation wherever the host finds it, not the batch around it, so a move that must be all-or-nothing across two signers needs one signer’s root entry over the whole tree |
factory set_pocket_wasm_hash |
admin | — | re-points every Managed purse at once (CAP-85); records the hash in the Pocket history and moves the epoch |
factory set_account_wasm_hash |
admin | — | re-points every account that opted into Managed at once (CAP-85) and is the hash update() installs for Manual ones; records the hash in the account history and moves the epoch |
factory seed_history |
admin | — | adds older hashes to a history so contracts still running them are recognised as behind. Idempotent, never moves a head or an entry; grants the admin no power it lacks, since the admin already controls the head |
factory create_account / upgrade |
admin | — | deploys a purse from the card’s key; idempotent. When the purse already exists it is returned as is, whatever curve and upgrade_policy were passed |
factory refresh |
— | — | permissionless keepalive: extends the factory and the "pocket" and "account" reference entries that exist. Reads no argument, moves no head, history, epoch or authorization, and emits no event |
factory fleet / pocket_wasm_hash / account_wasm_hash / get_account |
— | — | public views |
account add_card / remove_card / add_passkey / remove_passkey / abandon |
the account itself → __check_auth |
any signer on it, card or passkey | 1-of-n; remove_card and remove_passkey refuse the last signer of either kind. A handover is add_card / remove_card plus the purse’s chip-signed set_owner; nothing moves (ARCHITECTURE.md) |
account upgrade / update / set_upgrade_policy |
the account itself → __check_auth |
any signer on it | upgrade(hash) takes a signer-chosen hash; update() takes none and installs the factory’s account_wasm_hash. Both refuse under Managed (#511). set_upgrade_policy records the decision and marks one apply as owed only when it changes the policy |
account apply_upgrade_policy |
— | — | permissionless: only makes the executable match a decision a signer already signed. Single-shot: refuses (#512) unless one is pending. Emits apply_upgrade_policy |
account set_factory |
the account itself → __check_auth |
any signer on it | once only (#514). The one trust point of update(): clients take the address from their own configuration and show it in full. Resets a stored Managed to Manual and emits the SEP-50 mint |
account cards / passkeys / has_card / has_passkey / factory / version / upgrade_policy and the SEP-50 views |
— | — | public views |
collection create_collection / upgrade |
admin | — | deploys nfc-nft instances; ownership index |
collection assign_collectible |
the calling nfc-nft contract, which must be a registered collection | — | updates the ownership index on mint and clawback |
Digest / replay matrix
The terminal builds both smart-account signatures over the host payload, with the envelope from
chipAuthForDigest (purse) or accountChipSignature (account) in src/chain/chip-auth.ts.
Who authorizes decides when the chip signs.
- Plain-wasm authorizer (the Chimp account): a recording simulation reports the entries the
transaction needs, the signer signs each payload (
signAuthEntries), a chip or a passkey, and the footprint is refitted inenforcemode before submission. A passkey signs the same payload as the WebAuthn challenge. - Account that follows the fleet (
Managed) and purse: the authorization tree is declared and signed before anything is simulated, because a recording simulation fails inside the host when the authorizer’s executable is a fleet reference (preSignedAuthEntries); a purse is signed first whatever its policy. A wrong declaration fails in enforce-mode preflight, and a signed tree can never authorize more than it declares (CLIENT-INTEGRATION.md; chimpdao-terminaldocs/architecture.md§ Auth).
CAP-71’s sorobanCredentialsAddressV2 signs a different preimage,
HashIdPreimageSorobanAuthorizationWithAddress (V1’s plus the authorizing address). A recording
simulation returns V2 entries; entries the client builds are V1. The client keeps the variant an
entry arrived with and hashes the matching preimage.
| Path | What is signed | Envelope | Replay stops at |
|---|---|---|---|
Pocket (__check_auth) |
host SorobanAuthorization preimage (V1, or V2 …WithAddress when the entry carries V2 credentials) |
ChipAuth |
host nonce + expiration ledger |
Account (__check_auth), card |
the same preimage | AccountAuth { key, auth: <a card proof> } |
host nonce + expiration ledger |
Account (__check_auth), passkey |
the same preimage, as the WebAuthn challenge | AccountAuth { key, auth: Webauthn } |
host nonce + expiration ledger |
| nfc-nft attestation | call_digest(domain, contract, fn, args, nonce) |
ChipAuth |
per-chip monotonic nonce |
| prize attestation | same, domain chimpdao.prize.v1 |
ChipAuth |
its own per-chip nonce |
There is one smart-account digest, the host’s. Its V1 preimage carries the invocation and not the
authorizing address, so a purse and an account that list the same card verify the same signature
over it. A signature moves between the two only when the invocation names neither. Every call
here names its authorizer: a self-authorized call is made on the contract itself, a payment
carries from, and router.batch carries caller. A third-party function that requires the
authorization of an address absent from its arguments does not, and one tap could then count for
both; V2 credentials bind the address. Attestations are separated from both by domain.
Trust model
| Layer | Who can hurt you |
|---|---|
| Central (collection, factory, nfc mint/clawback/upgrade) | protocol admin |
| Fleet code | protocol admin: set_pocket_wasm_hash replaces the code of every Managed purse in one call, which is control of those purses and their funds; set_account_wasm_hash does the same for every account that opted into Managed, which holds the holder’s primary funds and signer sets. A Manual purse or account is out of reach of a push, and a holder who opts in must be told so before the signature. A release is canaried before it is pinned (RELEASE.md) |
| Router | nobody: no admin, no upgrade path, holds nothing |
whoever holds the physical chip, bounded by the purse float and its positions; for a Managed purse, also the fleet admin |
|
| Pocket recovery | nobody: sweep does not exist |
| Chimp account | any one of its signers (1-of-n), card or passkey, as peers; a lost or stolen signer is live until another signer removes it. A passkey is only as safe as the platform account that syncs it, which is that platform’s property, not the contract’s |
| Account recovery | none by ChimpDAO, ever. A Main is controlled by its signers; while it keeps one, any signer can remove a lost one. Losing every signer loses the account. remove_card and remove_passkey refuse the last signer of either kind; only abandon empties an account |
| NFT ownership | fixed at mint to the card’s own purse: no destination to choose, no later write |
There is one admin address per central contract (collection, each nfc-nft, the factory). set_admin
rotates it, one contract at a time and without a confirmation step, so the mainnet admin should be
a multisig account. create_collection gives a new nfc-nft the registry’s admin at that moment;
afterwards the two are independent.
Recorded design notes
Behaviour that a reviewer will ask about and that is kept on purpose.
call_digestwritesdomainwithout a length prefix. The domains in use are fixed and none is a prefix of another. Prefixing would change every signed digest in the terminal and iOS.- nfc-nft’s per-chip nonce guards a call that succeeds at most once, because
mintrefuses a card that has a token before it checks the signature. It is bound into the digest and kept. verify_for_cardbuilds aHash<32>from bytes through the SDK’sTryFromValForContractFn, which the SDK marks internal. The SDK offers no public constructor.- The factory adopts a purse that already exists.
mintdoes not compare its curve or policy with the attested ones; only the admin can create a purse before the mint. - The router holds nothing by design. An asset sent to its address, or a role or allowance
granted to it, is usable by whoever calls
batch. Never fund or grant anything to it. - A passkey never authorizes a purse. A purse answers to its chip alone,
sweepdoes not exist, andPocket::ownergrants nothing, so a Main’s signers, passkeys included, have no path to a card’s float.a_passkey_proof_cannot_authorize_a_pursepins it. upgrade(hash)never calls the factory, so an outage or a bad pin can never be the reason an account cannot be upgraded;update()andapply_upgrade_policyare the only paths that read it.