Skip to main content

Verification Badges

SphereNet uses verification badges for on-chain attestations of trust and compliance. Each badge links a verifier (e.g., a KYC provider, institution, or on-chain program) to a public key (a user-controlled wallet or a program-derived address).

The Badge Program contains the instruction logic for creating and updating badges, while Badge Accounts record the verification status of a wallet by a verifier.

Badge Program​

The Badge Program manages the lifecycle of Badge Accounts. It supports the following actions:

  • InitializeAccount
    Creates a new Badge Account for a given verifier–wallet pair with is_verified set to false.

  • Verify
    Sets is_verified to true. Can also set or update expiration_slot and metadata.

  • Revoke
    Sets is_verified to false, removes expiration_slot, and optionally updates metadata.

  • UpdateMetadata
    Allows the verifier to add, modify, or remove key-value pairs in metadata.

  • CloseAccount
    Deletes the Badge Account and reclaims any associated on-chain rent.

Badge Accounts​

A Badge Account is the on-chain structure that holds a verifier's attestation for a wallet. Its structure is:

pub struct BadgeAccount {
    pub verifier: Pubkey,
    pub wallet: Pubkey,
    pub is_verified: bool,
    pub expiration_slot: Option<u64>,
    pub metadata: Vec<(String, String)>
}

Field Descriptions​

  • verifier: The public key authorized to perform verification operations.
  • wallet: The address being verified.
  • is_verified: The current verification status.
  • expiration_slot: (Optional) A block slot after which the badge expires.
  • metadata: A list of key-value pairs (strings) for additional details.

A verification check confirms that is_verified is true and, if set, that the current block slot is less than expiration_slot. The CloseAccount instruction removes the Badge Account when no longer needed.

Badge Account

Associated Badge Account​

An Associated Badge Account (ABA) simplifies finding a Badge Account for a specific verifier–wallet pair. The ABA's address is derived deterministically using the wallet's public key, the Badge Program's ID, and the verifier's public key:

ABA_pubkey = Pubkey::find_program_address(
   &[
        wallet_address.to_bytes(),
        badge_program_id.to_bytes(),
        verifier_address.to_bytes(),
    ],
    ABA_program_id,
);

Key Points​

  • Determinism: The address can be computed off-chain by anyone.
  • Collision Avoidance: The derivation prevents address collisions.
  • Decentralized Lookup: No global registry is needed.
Associated Badge Account

Programmatic Verification​

On-chain programs can act as verifiers. For example, a user may submit a zero-knowledge proof to show they meet an age requirement or reside in a specific jurisdiction. Once validated, the program calls Verify to set is_verified to true and may set an expiration_slot.

Account Classification Program​

The Account Classification Program works as follows:

  1. A user interacts with the program to classify their account.
  2. The program creates an ABA for the wallet.
  3. It sets metadata with a key-value pair (e.g., "type": "<account_type>"), where <account_type> can be "individual", "institution", or another classification.
  4. No expiration_slot is set, so the classification is permanent.
  5. Once set, the classification cannot be changed.

This system uses the Badge Account structure for stable account classification.