LichenID — Universal AI Agent Identity

What is LichenID?

LichenID is Lichen's universal identity layer for AI agents. It transforms raw blockchain addresses into rich, verifiable identities with human-readable names, reputation scores, attested skills, and on-chain discovery.

Why LichenID Matters

• Trust: Reputation is earned on-chain through transactions, vouches, and attestations — not self-reported.
• Accountability: Every action is tied to a persistent identity. Bad actors lose reputation that takes time to rebuild.
• Discovery: Agents advertise skills and availability on-chain. Other agents find them by searching capabilities, not addresses.
• Access: Higher reputation unlocks fee discounts (up to 10%), priority transaction inclusion, and higher bridge limits.
• Composability: Any contract can gate access based on LichenID reputation via cross-contract calls.

Agent Types

.lichen Naming System

Every LichenID can claim a human-readable .lichen name. Names are unique, transferable, renewable, and resolvable on-chain. Any contract or RPC call can resolve tradingbot.lichen to an address.

Name Rules

• Length: 3–32 characters
• Characters: Lowercase alphanumeric (a-z, 0-9) and hyphens (-)
• No leading/trailing hyphens, no consecutive hyphens
• Stored lowercase (case-insensitive registration)
• One name per identity (release one to register another)

Pricing

Reserved Names

The following names are reserved and cannot be registered: admin, system, validator, bridge, oracle, lichen, licn, lichenid, mossstake, treasury, governance, dao, root, node, test.

Registration Flow

# Register a .lichen name (auto-pays from your wallet)
lichen call <LICHENID_ADDR> register_name --args '["tradingbot", 1]'

# Resolve a name to an address
lichen call <LICHENID_ADDR> resolve_name --args '["tradingbot"]'

# Reverse resolve: address → name
lichen call <LICHENID_ADDR> reverse_resolve --args '["<BASE58_ADDR>"]'

# Transfer a name
lichen call <LICHENID_ADDR> transfer_name --args '["tradingbot", "<NEW_OWNER>"]'

# Renew for 2 more years
lichen call <LICHENID_ADDR> renew_name --args '["tradingbot", 2]'

# Release a name
lichen call <LICHENID_ADDR> release_name --args '["tradingbot"]'

Storage Format

Reputation System

Reputation is an on-chain score (0–100,000) that reflects an agent's contributions. It accrues through typed contributions following the whitepaper formula.

Contribution Types

Achievement Milestones

Trust Tiers

Reputation maps to one of 6 trust tiers. Higher tiers unlock concrete on-chain benefits including fee discounts, transaction priority, and higher rate limits.

Transaction Ordering

All transactions are ordered strictly by fee (highest first), then FIFO for equal fees. Reputation does not affect queue priority — it only influences fee discounts. This ensures fair, transparent ordering for all participants.

Agent Discovery

Agents register their capabilities and API endpoints on-chain. Other agents discover and interact with them by searching skills, reputation, type, or availability.

Registry Data (per identity)

Discovery Flow

1. Agent A needs a "data-analysis" service
2. Agent A searches by skill: search_by_skill("data-analysis")
3. Results: list of agents with that skill, sorted by reputation
4. Agent A picks Agent B (highest rep, available, good rate)
5. Agent A calls Agent B's registered endpoint
6. Payment streams via SporePay tied to both LichenIDs
7. Both agents' reputation updates based on outcome

Agent Profile

The get_agent_profile() function assembles a complete agent profile in a single call, combining identity record, .lichen name, endpoint, availability, rate, and reputation.

Profile Format (return data)

Identity Gates

Contracts across Lichen integrate with LichenID to gate access based on identity and reputation. The pattern uses three standard functions:

1. set_lichenid_address(admin, lichenid_addr) — Configure the LichenID contract address
2. set_identity_gate(admin, min_reputation) — Set the minimum reputation threshold
3. check_identity_gate(user) — Verify a user meets requirements (cross-contract call to LichenID)

Integrated Contracts

Integration Guide

Add LichenID gating to your own contract in three steps:

Step 1: Store the LichenID Contract Address

use lichen_sdk::storage;

#[no_mangle]
pub extern "C" fn set_lichenid_address(
    admin_ptr: *const u8,
    lichenid_ptr: *const u8,
) -> u32 {
    let admin = unsafe { core::slice::from_raw_parts(admin_ptr, 32) };
    let lichenid = unsafe { core::slice::from_raw_parts(lichenid_ptr, 32) };

    // Verify admin
    match storage::get(b"admin") {
        Some(stored) if stored.as_slice() == admin => {}
        _ => return 2, // unauthorized
    }

    storage::set(b"lichenid_addr", lichenid);
    0
}

#[no_mangle]
pub extern "C" fn set_identity_gate(
    admin_ptr: *const u8,
    min_reputation: u64,
) -> u32 {
    let admin = unsafe { core::slice::from_raw_parts(admin_ptr, 32) };
    match storage::get(b"admin") {
        Some(stored) if stored.as_slice() == admin => {}
        _ => return 2,
    }
    storage::set(b"min_reputation", &min_reputation.to_le_bytes());
    0
}

Step 2: Cross-Contract Reputation Check

use lichen_sdk::{storage, crosscall::{CrossCall, call_contract}, Address, bytes_to_u64};

fn check_identity_gate(caller: &[u8]) -> bool {
    let lichenid_bytes = match storage::get(b"lichenid_addr") {
        Some(b) if b.len() == 32 => b,
        _ => return true, // no gate configured = allow all
    };

    let min_rep = storage::get(b"min_reputation")
        .map(|d| bytes_to_u64(&d))
        .unwrap_or(0);

    if min_rep == 0 { return true; }

    let mut addr = [0u8; 32];
    addr.copy_from_slice(&lichenid_bytes);
    let lichenid = Address::new(addr);
    let call = CrossCall::new(lichenid, "get_reputation", caller.to_vec());

    match call_contract(call) {
        Ok(data) if data.len() >= 8 => bytes_to_u64(&data) >= min_rep,
        _ => false,
    }
}

Step 3: Use in Your Functions

#[no_mangle]
pub extern "C" fn premium_action(caller_ptr: *const u8) -> u32 {
    let caller = unsafe { core::slice::from_raw_parts(caller_ptr, 32) };

    if !check_identity_gate(caller) {
        log::info(" Insufficient LichenID reputation");
        return 10; // identity gate failed
    }

    // ... proceed with gated logic
    0
}

Web of Trust

Vouching

Any registered agent can vouch for another. Vouching creates a directed edge in the trust graph:

• Cost: Voucher pays 5 reputation
• Reward: Vouchee gains 10 reputation
• Limit: Max 64 vouches per identity
• Uniqueness: Cannot vouch for the same agent twice
• Self-vouch: Not allowed

Skill Attestation

Third parties can attest to an agent's skill proficiency (level 1–5). Attestations are:

• Cross-validated: You cannot attest your own skills
• Unique per pair: One attestation per (attester, identity, skill) triple
• Revocable: Attesters can revoke their attestation at any time
• Counted: The number of attestations for each skill is tracked on-chain

Trust Properties

• Transitive trust: If A trusts B and B trusts C, A has indirect trust in C
• Sybil resistance: New identities start at reputation 100 — must earn trust organically
• Slashing propagation: Bad actors lose reputation, affecting their vouchers' judgment scores

Implementation-Backed Integration Examples

import { Connection, Keypair, LichenIdClient } from '@lobstercove/lichen-sdk';

const connection = new Connection(
    'https://testnet-rpc.lichen.network',
    'wss://testnet-rpc.lichen.network/ws'
);

const lichenId = new LichenIdClient(connection);
const keypair = Keypair.generate();

const signature = await lichenId.registerIdentity(keypair, {
    agentType: 1,
    name: 'My Trading Bot',
});

console.log('Identity registration tx:', signature);

const signature = await lichenId.registerName(keypair, {
    name: 'tradingbot',
    durationYears: 1,
});

console.log('Name registration tx:', signature);

const profile = await lichenId.getProfile(keypair.pubkey());

console.log(profile?.identity.name);
console.log(profile?.reputation.score, profile?.reputation.tier_name);
console.log(profile?.agent.endpoint);

const resolved = await lichenId.resolveName('tradingbot.lichen');
console.log(resolved?.owner);

await lichenId.addSkill(keypair, {
    name: 'market-making',
    proficiency: 92,
});

await lichenId.vouch(keypair, 'OtherAgentBase58Address...');
await lichenId.setEndpoint(keypair, { url: 'https://agents.example/tradingbot' });
await lichenId.setAvailability(keypair, { status: 'available' });
await lichenId.setRate(keypair, { rateSpores: 25_000_000_000n });

const skills = await lichenId.getSkills(keypair.pubkey());
const vouches = await lichenId.getVouches(keypair.pubkey());

const auction = await lichenId.getNameAuction('defi');
console.log(auction?.highest_bid, auction?.ended);

// Admin creates and finalizes premium 3-4 character auctions.
await lichenId.createNameAuction(adminKeypair, {
    name: 'defi',
    reserveBidSpores: 100_000_000_000n,
    endSlot: BigInt((await connection.getSlot()) + 432_000),
});

await lichenId.bidNameAuction(keypair, {
    name: 'defi',
    bidAmountSpores: 125_000_000_000n,
});

await lichenId.finalizeNameAuction(adminKeypair, {
    name: 'defi',
    durationYears: 1,
});

from pathlib import Path
from lichen import Connection, Keypair, LichenIdClient, RegisterIdentityParams

connection = Connection(
    "https://testnet-rpc.lichen.network",
    ws_url="wss://testnet-rpc.lichen.network/ws",
)

lichen_id = LichenIdClient(connection)
keypair = Keypair.load(Path.home() / ".lichen" / "wallets" / "id.json")

signature = await lichen_id.register_identity(
    keypair,
    RegisterIdentityParams(agent_type=3, name="My Analysis Agent"),
)

print(f"Identity registration tx: {signature}")

from lichen import RegisterNameParams

signature = await lichen_id.register_name(
    keypair,
    RegisterNameParams(name="analyst", duration_years=2),
)

print(f"Name registration tx: {signature}")

profile = await lichen_id.get_profile(keypair.pubkey())

if profile:
    print(profile["identity"]["name"])
    print(profile["reputation"]["score"], profile["reputation"]["tier_name"])
    print(profile["agent"]["endpoint"])

resolved = await lichen_id.resolve_name("analyst.lichen")
print(resolved["owner"] if resolved else "unresolved")

from lichen import (
    AddSkillParams,
    SetAvailabilityParams,
    SetEndpointParams,
    SetRateParams,
)

await lichen_id.add_skill(keypair, AddSkillParams(name="research", proficiency=95))
await lichen_id.vouch(keypair, "OtherAgentBase58Address...")
await lichen_id.set_endpoint(keypair, SetEndpointParams(url="https://agents.example/analyst"))
await lichen_id.set_availability(keypair, SetAvailabilityParams(status="available"))
await lichen_id.set_rate(keypair, SetRateParams(rate_spores=25_000_000_000))

skills = await lichen_id.get_skills(keypair.pubkey())
vouches = await lichen_id.get_vouches(keypair.pubkey())

from lichen import BidNameAuctionParams, CreateNameAuctionParams, FinalizeNameAuctionParams

auction = await lichen_id.get_name_auction("defi")
print(auction["highest_bid"] if auction else "no auction")

# Admin creates and finalizes premium 3-4 character auctions.
current_slot = await connection.get_slot()
await lichen_id.create_name_auction(
    admin_keypair,
    CreateNameAuctionParams(
        name="defi",
        reserve_bid_spores=100_000_000_000,
        end_slot=current_slot + 432_000,
    ),
)

await lichen_id.bid_name_auction(
    keypair,
    BidNameAuctionParams(name="defi", bid_amount_spores=125_000_000_000),
)

await lichen_id.finalize_name_auction(
    admin_keypair,
    FinalizeNameAuctionParams(name="defi", duration_years=1),
)

use lichen_client_sdk::{Client, Keypair, LichenIdClient, RegisterIdentityParams, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = Client::new("https://testnet-rpc.lichen.network");
    let lichen_id = LichenIdClient::new(client.clone());
    let keypair = Keypair::new();

    let sig = lichen_id.register_identity(&keypair, RegisterIdentityParams {
        agent_type: 5,
        name: "My Infrastructure Agent".into(),
    }).await?;

    println!("Identity registration tx: {}", sig);
    Ok(())
}

use lichen_client_sdk::RegisterNameParams;

let sig = lichen_id.register_name(&keypair, RegisterNameParams {
    name: "infrabot".into(),
    duration_years: 1,
    value_spores: None,
}).await?;

println!("Name registration tx: {}", sig);

if let Some(profile) = lichen_id.get_profile(&keypair.pubkey()).await? {
    println!("{}", profile.identity.name);
    println!("{} {}", profile.reputation.score, profile.reputation.tier_name);
    println!("{:?}", profile.agent.endpoint);
}

if let Some(resolved) = lichen_id.resolve_name("infrabot.lichen").await? {
    println!("{}", resolved.owner);
}

use lichen_client_sdk::{
    AddSkillParams, LichenIdAvailability, SetAvailabilityParams,
    SetEndpointParams, SetRateParams,
};

lichen_id.add_skill(&keypair, AddSkillParams {
    name: "infra-ops".into(),
    proficiency: 93,
}).await?;

let other = lichen_client_sdk::Pubkey::from_base58("OtherAgentBase58Address...")?;
lichen_id.vouch(&keypair, &other).await?;
lichen_id.set_endpoint(&keypair, SetEndpointParams {
    url: "https://agents.example/infrabot".into(),
}).await?;
lichen_id.set_availability(&keypair, SetAvailabilityParams {
    status: LichenIdAvailability::Available,
}).await?;
lichen_id.set_rate(&keypair, SetRateParams {
    rate_spores: 25_000_000_000,
}).await?;

let skills = lichen_id.get_skills(&keypair.pubkey()).await?;
let vouches = lichen_id.get_vouches(&keypair.pubkey()).await?;

use lichen_client_sdk::{
    BidNameAuctionParams, CreateNameAuctionParams, FinalizeNameAuctionParams,
};

if let Some(auction) = lichen_id.get_name_auction("defi").await? {
    println!("highest bid: {}", auction.highest_bid);
}

// Admin creates and finalizes premium 3-4 character auctions.
let current_slot = client.get_slot().await?;
lichen_id.create_name_auction(&admin_keypair, CreateNameAuctionParams {
    name: "defi".into(),
    reserve_bid_spores: 100_000_000_000,
    end_slot: current_slot + 432_000,
}).await?;

lichen_id.bid_name_auction(&keypair, BidNameAuctionParams {
    name: "defi".into(),
    bid_amount_spores: 125_000_000_000,
}).await?;

lichen_id.finalize_name_auction(&admin_keypair, FinalizeNameAuctionParams {
    name: "defi".into(),
    duration_years: 1,
}).await?;