Skip to main content

Security

Antseed separates a buyer's deposit balance from the node wallet. USDC committed to service payments is held by AntseedDeposits; the node signs spending authorizations. Incoming USDC can be swept from the node wallet into the deposit contract through a gasless authorization.

Identity​

Each node uses a secp256k1 private key. Its EVM address is the peer identity and payment-signing identity. A separate wallet can fund the node's deposit or act as its deposits operator; those roles do not have to share the node key.

FunctionMechanism
P2P identityEIP-191 personal_sign with domain tags ("antseed-data-v1:", "antseed-msg-v1:"), verified via ecrecover
Payment authorizationEIP-712 signatures (ReserveAuth, SpendingAuth)
PeerIdEVM address (40 hex chars, no 0x prefix)

Signing identity vs funding wallet​

The signing identity signs protocol messages and payment authorizations. Gasless buyer funding can send USDC to this address first, then use a signed authorization and a permissionless relayer to sweep it into AntseedDeposits. Sellers also use their node wallet for transaction gas and USDC earnings.

An external funding wallet can instead approve USDC and call deposit(buyer, amount) directly. Funding a buyer does not automatically make that wallet the buyer's operator.

The deposits operator can withdraw the buyer's available deposit balance. The buyer authorizes its initial operator with an EIP-712 signature; the current operator controls subsequent operator transfers. Check getOperator(buyer) rather than assuming the funding wallet has withdrawal authority.

Key storage​

EnvironmentProtection
Desktop appElectron safeStorage API encrypts the secp256k1 private key at rest using the OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret). On first launch after upgrade, plaintext identity.key is auto-encrypted and the original deleted.
CLI / serveridentity.key in the data directory (~/.antseed/ by default), plaintext unless you encrypt it with a passphrase (ANTSEED_PASSPHRASE; see Wallet keys). On servers you can instead pass the key through ANTSEED_IDENTITY_HEX from a secrets manager.

Auto vs manual approval​

Payment signatures can be issued in two modes:

ModeFlowUse case
AutoNode receives 402 → signs ReserveAuth and SpendingAuth internally → sends to seller → seller calls reserve()Gateway, server, and CLI deployments
ManualNode receives 402 → propagates to the application → the application signs and returns the authorization in the x-antseed-spending-auth header → seller calls reserve()Applications that want an approval step

Both modes produce identical on-chain outcomes. The difference is whether the signing step requires user interaction. Each ReserveAuth is scoped to a specific seller, capped by maxAmount, and expires at deadline.

Risk bounds​

ScenarioSigning identity exposedFunding wallet exposedMaximum loss
Node compromisedYesNot if its key is kept separatelyAuthorized deposit spending, node-wallet assets, and any roles held by that key
Signing key extractedYesNot if its key is kept separatelySame exposure as the signing identity
Funding wallet compromisedNot necessarilyYesWallet assets; available deposits too if it is their operator
Deposits operator compromisedNot necessarilyDepends on key reuseAvailable deposits for accounts it operates
Deposits contract exploitN/AN/AAll deposited funds across all users

These roles can use the same address, in which case their risks combine. A separate funding wallet is not exposed merely because it previously funded a buyer, but shared keys, allowances, and operator permissions must be considered.

Protocol-level controls​

All communication happens over an untrusted network. Every trust-critical operation is cryptographically verified:

  • secp256k1 peer identity: every node has a unique keypair; discovery metadata and connection handshakes are signed with EIP-191 personal_sign
  • Replay-resistant authentication: connection envelopes include nonce + timestamp with a 30-second skew check and a nonce replay guard
  • Bounded resource usage: frame sizes, upload caps, stream durations, and concurrent connections are all hard-limited
  • On-chain settlement: EIP-712 signed ReserveAuth and SpendingAuth with per-seller, per-session, time-bounded authorization

Buyer-seller flow controls​

StageControls
DiscoverySigned metadata with freshness checks, topic normalization, private IP filtering
ConnectionEIP-191 signed intro envelopes with nonce replay guard, timestamp skew rejection, per-IP inbound connection cap (64)
TransportEncrypted TCP (X25519 + AES-256-GCM) or DTLS WebRTC when the peer supports it; frame type and size validation (64 MiB max), fail-closed on decode errors, request and stream timeouts
Upload/StreamPer-request cap (64 MiB), global pending cap (256 MiB), upload timeout (120s), bounded stream buffers and configurable duration limits
MeteringSeller reports usage per request; the buyer recomputes the cost from the seller's published prices before signing the next cumulative SpendingAuth (Payments)
Payment402 gating until ReserveAuth is committed on-chain via reserve(), bounded by maxAmount and deadline

Default limits​

Buyer request and stream defaults are defined in packages/buyer-core and the CLI configuration. They are configurable; upload and connection limits are separate transport controls.

ParameterDefault
Buyer request timeout5 min
Max stream buffer16 MiB
Buyer max stream duration30 min
Per-upload cap64 MiB
Global pending upload cap256 MiB
Upload timeout120 s
Node metadata fetch timeout1.5 s
Max inbound connections per IP64

Best practices​

  1. Keep treasury and operator keys separate from the node where possible. Use deposit(buyer, amount) for direct external funding, or the gasless sweep flow (Payments) when funding the node address. Minimize assets left in the hot wallet.
  2. Deposit only what you need for a session. Top up as needed rather than pre-loading large amounts into AntseedDeposits.
  3. If you embed the node SDK, keep allowPrivateIPs off in production (the SDK default).
  4. Keep signature verification and stale metadata rejection enabled (both on by default).
  5. Encrypted TCP (transport.tcp-enc.v1) is used automatically between peers that advertise it. SDK users can set the requireSecureTransport node option to refuse plaintext TCP and unsigned SDP.
  6. On servers, use ANTSEED_IDENTITY_HEX with a secrets manager instead of storing keys on disk.
  7. Back up your secp256k1 private key — it is the only way to recover your PeerId (EVM address) and on-chain wallet.