DOCS / PROTOCOL / CARD AUTHORIZATION

Card authorization

Live on testnetLocking · Planned

How a card becomes a genuine Chimp card, joins an account, authorises and leaves it. Everything on this page runs on the testnet contracts today, except locking.

LAST UPDATED · 2026-10-05

Card types

Each card carries a secure chip that generates and keeps its own key. Two card types are supported: one protected by a PIN, one without a PIN.

CARDPINSTATUS

Cards with a PIN

PINYes · 4 digits, chosen at activation. After three wrong PINs the card locks. An unlock code is shown once when the PIN is set.

STATUSTested on iPhone

Cards without a PIN

PINNo · one tap signs

STATUSSupported in code, not yet tested on a physical card

LIMITATION

Cards without a PIN work like cash: whoever finds one can spend what is on its own wallet.

Registration

Live on testnet

Only ChimpDAO's admin can register a card, with one call to the card registry (mint). The call needs two signatures: the admin's, and an attestation from the card's chip over this exact call (the registry, the function, the card's public key and the terms it is registered under) and a per-card nonce. This proves the physical card was present.

In that one call the registry creates the card's token, deploys the card's own wallet and makes that wallet the token's permanent owner. The token has no transfer function: it never leaves the card's wallet. A card that is not registered is refused by the app.

Activation

Live on testnet

The owner taps the card and chooses a PIN (on cards that have one). Before anything is paid, the app has the card sign a random challenge and checks the signature on the phone (proof of possession). Then two transactions follow, both paid by ChimpDAO: the Main account is deployed with this card as its founding card (no card signature needed), and the card signs set_owner, which points its own wallet at that account.

Adding a card

Live on testnet

A second card joins an account in two taps: the new card points its own wallet at the account (set_owner), then a card already on the account approves add_card. Any card of the account can authorise any payment from the Main account (one of n).

Replay protection

Live on testnet

WHATPROTECTIONENFORCED BY

Payments and account operations

PROTECTIONEach signed authorisation carries a random nonce and an expiration ledger (about 10 minutes for card signatures). A used nonce or a late authorisation is refused.

ENFORCED BYThe Stellar network. The contracts keep no nonce of their own.

Card registration

PROTECTIONThe attestation signs a per-card nonce kept by the registry (get_nonce). A successful registration consumes it.

ENFORCED BYThe card registry

Removal

Live on testnet

A card is removed from its account with remove_card, approved by any card of that account, including the card that leaves. A lost card is removed by another card of the same account. The contract refuses to remove the last card: an account with no card could never authorise anything again.

A removed card keeps its own wallet and what is on it: that wallet only obeys its card. ChimpDAO's admin can also take back a card's token (clawback), a central escape hatch of the registry.

Locking

Planned

There is no lock or freeze function in the contracts today. Until another card removes it, a lost card stays a valid signer of its Main account.

What the contract tests cover

The contract tests run with a software chip. What they check, and what they do not check yet:

CHECKCOVERED

Registration with a valid attestation, for both card types

COVEREDYes

Registration with an invalid signature is refused

COVEREDYes

Registration under terms the chip did not sign is refused

COVEREDYes

A second registration of the same card is refused

COVEREDYes, because the card already has a token

A successful registration consumes the card's nonce

COVEREDYes

A replayed attestation is refused by the nonce check itself

COVEREDNot yet · Planned

A card's wallet accepts its own card and refuses another card, a bad signature and a signature over another payload

COVEREDYes

Removing the last card, a duplicate card or an unlisted card is refused

COVEREDYes

An expired authorisation is refused

COVEREDNot yet · Planned

A removed card can no longer authorise for the account

COVEREDNot yet · Planned

Edit this page in the repositoryCHIMPDAO DOCS · TESTNET