Smart Contract Architecture

How Cardless ID anchors identity credentials to a public blockchain

Cardless ID currently runs on the Algorand blockchain. The underlying architecture — an on-chain issuer registry plus non-transferable credential tokens — is blockchain-agnostic and can be ported to any chain that supports smart contracts.

Overview

When a user's identity is verified, Cardless ID records the credential in two places:

A W3C Verifiable Credential stored locally in the user's wallet app (off-chain, private).
A non-transferable NFT minted on the blockchain (on-chain, public proof-of-issuance).

The on-chain record contains no personal data — only a cryptographic hash and metadata about the issuer. This lets any third party independently verify that a credential was legitimately issued without accessing any private information.

Architecture Overview

The Issuer Registry Smart Contract

A smart contract deployed on Algorand maintains a registry of authorized credential issuers. The contract exposes these core operations:

Method	Description
addIssuer()	Registers a new authorized issuer with name and URL metadata
removeIssuer()	Permanently removes an issuer from the registry
revokeIssuer()	Suspends an issuer (soft or hard revocation)
reinstateIssuer()	Restores a previously suspended issuer
isAuthorized()	Returns whether an issuer is currently active — callable by anyone, no permission required
revokeCredential()	Marks a specific credential as revoked. The ID is the `urn:uuid:…` string assigned to the W3C credential at issuance and stored in the NFT's on-chain metadata
transferAdmin()	Transfers administrative control of the registry

Trustless verification: Because isAuthorized() is a public read-only call, any verifier can check issuer status directly against the blockchain without trusting Cardless ID's servers.

Credential NFTs (Algorand Standard Assets)

Each verified credential is minted as an Algorand Standard Asset (ASA) with properties that make it behave like a non-transferable "soulbound" token:

Asset Properties

total: 1 — unique, one-of-a-kind token
decimals: 0 — indivisible
unitName: "CIDCRED"
defaultFrozen: false — frozen after transfer

Issuer Controls

manager — issuer can update metadata
freeze — issuer freezes token after delivery
clawback — issuer can revoke the credential

Issuance Flow

On-chain metadata follows the ARC-69 standard and includes the credential ID, a SHA-256 composite hash (for duplicate detection), and the issuance timestamp. No name, birthdate, or other personal data is written to the chain.

Costs

There is a real (though small) cost in ALGO for each credential issuance. These fees are paid by the issuer, not the end user.

Operation	Cost	Notes
Wallet funding (new wallets only)	~0.2 ALGO	0.1 ALGO min balance + tx fees; one-time per wallet
ASA creation (mint)	0.001 ALGO	Standard Algorand transaction fee
ASA transfer	0.001 ALGO	Deliver credential to recipient wallet
ASA freeze	0.001 ALGO	Lock credential as non-transferable
Total per issuance (existing wallet)	~0.003 ALGO	3 transactions
Total per issuance (new wallet)	~0.203 ALGO	Includes one-time wallet funding

ALGO prices fluctuate. At typical market rates the per-issuance cost is a fraction of a US cent for existing wallets, or a few cents for a brand-new wallet. The 0.1 ALGO minimum balance is locked in the recipient's wallet (not burned) and can be recovered if the wallet is ever closed.

Portability to Other Blockchains

Algorand was chosen for its low transaction fees, fast finality (~3.3s blocks), and energy efficiency. However, the Cardless ID architecture does not depend on any Algorand-specific feature. The two chain-specific modules are:

app/utils/algorand.ts — client setup, wallet funding, transaction helpers
app/utils/nft-credentials.ts — ASA mint, transfer, freeze, clawback, and metadata reads

All other code — the W3C credential format, the issuance API, the verification flow, and the wallet app — is chain-agnostic. Porting to another chain requires replacing these two modules with equivalents for the target platform:

Ethereum / L2s

Deploy an ERC-5484 "Soulbound Token" contract for non-transferable credentials. Use an ERC-1967 proxy for the issuer registry. Gas costs are higher but L2s (Polygon, Base, Arbitrum) bring them close to Algorand levels.

Solana

Use Metaplex's Non-Transferable Token standard or a custom SPL token with freeze authority held by the issuer. The Solana Programs layer maps directly to the AVM smart contract used here.

Other AVM chains

Any AVM-compatible chain (Voi, etc.) can run the existing contracts with zero or minimal changes, since they share the same virtual machine and ASA standard.