RFC: define AgentBook re-registration, revocation, and wallet rotation

[realmehmetali]

Context

AgentBook's public contract and tooling currently describe different lifecycle semantics:

• AgentBook.register(...) is nonce-based and overwrites lookupHuman[agent]; testCanReRegisterAgent explicitly covers re-registration.
• The registration guide tells relays to refuse sponsorship when an address is already registered.
• The hosted flow in How to unregister an agent #23 reports ALREADY_REGISTERED, preventing a user from replacing an earlier registration.
• The x402 documentation says revoked registrations take effect at lookup time, but IAgentBook currently has no revocation operation.

That leaves recovery, re-verification, and key rotation behavior unclear for users and integrators.

Goals

1. Let a human replace an obsolete registration after their World ID verification state changes.
2. Let a human make a lost or compromised agent wallet stop resolving as human-backed.
3. Define a safe path from an old agent wallet to a new one.
4. Keep CLI, relay, contract, and verifier behavior consistent.
5. Preserve the existing privacy property that applications receive an anonymous human identifier rather than a civil identity.

Proposed order

Phase 0: align existing re-registration behavior

Treat the current register function as an upsert:

• the CLI continues to fetch getNextNonce(agent)
• relays may sponsor a valid next-nonce re-registration instead of returning ALREADY_REGISTERED
• relay anti-abuse controls should be independent of whether the address already has a mapping
• CLI/docs explain that re-registration replaces the current mapping

This would directly address #23 without changing the contract interface.

Phase 1: specify revocation

Add an explicit active/inactive lifecycle whose lookup semantics remain simple for x402 consumers: an inactive agent resolves as unregistered.

The authorization model needs a maintainer decision. Candidate approaches:

• a fresh World ID proof bound to (agent, nonce, "revoke")
• an agent-wallet signature plus a fresh World ID proof
• wallet signature alone (simple, but insufficient when the wallet is compromised)

A World ID-authorized path appears necessary for compromised-key recovery.

Phase 2: specify rotation

Rotation could either be:

• one atomic operation binding (oldAgent, newAgent, nonce), or
• revocation of the old address followed by registration of the new one

An atomic operation gives clearer all-or-nothing behavior, but it may create a more explicit public link between the old and new wallet. That privacy tradeoff should be intentional.

Suggested invariants

• A stale proof cannot register, restore, revoke, or rotate an agent.
• No caller can attach an address to a human identifier without a valid World ID proof bound to the exact operation.
• Revocation takes effect immediately for lookupHuman-based authorization.
• A compromised wallet cannot block its human from recovering through a fresh proof.
• Multiple agents per human remain supported unless the product policy explicitly changes.
• Relayers cannot alter the target address or operation encoded in the proof signal.
• Events are sufficient for indexers to reconstruct active state without exposing additional identity data.

Interface questions

1. Should lookupHuman(agent) continue returning 0 for both never-registered and revoked agents, or should a richer status view be added alongside it?
2. Should re-registration be allowed to replace the mapped human identifier, or only refresh the same identifier?
3. Should rotation require control of the old wallet, a fresh World ID proof, or both?
4. Is public old-to-new wallet linkage acceptable, or should rotation be represented as independent revoke/register operations?
5. Is the canonical deployment upgradeable/migratable, or should lifecycle support be introduced in a versioned AgentBook contract?

Acceptance criteria for an implementation

• contract tests for re-registration, revocation, replayed nonces/proofs, compromised-wallet recovery, and rotation failure atomicity
• CLI commands and status output covering each lifecycle state
• relay behavior matching the contract specification
• migration/versioning guidance for existing registrations
• documentation clarifying privacy and threat-model tradeoffs

If the maintainers agree with Phase 0, I can prepare the relay/CLI/docs patch separately while the contract-level decisions are discussed.

Disclosure

This RFC was prepared with AI assistance from review of this public repository and public issue #23 only. No private code, production data, or internal implementation details were used.