Architecture / authentication
Wallet authentication
SEICHO uses a human-readable off-chain wallet signature to prove control of an address. Authentication does not approve tokens and does not submit an on-chain transaction.
Signature vs transaction
| Action | On-chain | Can move funds | Purpose |
|---|---|---|---|
Login signaturesignMessage | No | No | Proves control of the connected wallet. |
ERC-20 approvalapprove | Yes | Creates a finite allowance | Authorizes the core contract as spender. |
Subscriptionsubscribe | Yes | Transfers the exact computed payment | Creates or extends paid access. |
Login sequence
- The frontend submits the wallet address and chain ID to the nonce endpoint.
- The backend generates a 64-character opaque nonce with a five-minute expiry.
- The nonce is stored with wallet, chain, purpose and payload hash.
- The wallet signs the exact message returned by the backend.
- The backend reconstructs the message and verifies the signature with
viem.verifyMessage. - The nonce is consumed atomically before the session is committed.
- The session expires no later than 31 days or the verified subscription expiry, whichever occurs first.
Message format
The production login message follows this format:
SEICHO Authentication
Action: wallet_login
Wallet: 0xYourWalletAddress
Chain ID: 8453
Payload Hash: <64 lowercase hexadecimal characters>
Nonce: <64 lowercase hexadecimal characters>
Sign this message to authenticate. This does not authorize a blockchain transaction.Replay protection
- Nonce lifetime
- 5 minutes
- Nonce use
- Single-use; consumed within the login transaction
- Binding
- Wallet address, Base chain ID, purpose and payload hash
- Session maximum
- 31 days, capped by subscription expiry
- Server verification
- Message reconstructed and signature recovered server-side
Other signatures
Logged-in wallet users may be asked for similarly structured security signatures when linking or unlinking a Google identity or revoking a trusted device. These messages include a purpose-specific payload hash and a single-use nonce.
Administrative content mutations use a separate SEICHO Admin Action message containing domain, chain ID, action, resource, payload hash, nonce and expiry. The backend accepts it only from the authenticated wallet that currently matches the contract owner().