# Billions

> Billions Agent Identity Plugin for OpenClaw, providing identity management and authentication capabilities using the Iden3 protocol. Allow proof/verify credentials, manage DIDs, and handle authentication flows.

- Skill: `billionsnetwork/billions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add billionsnetwork/billions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/billionsnetwork/billions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: billionsnetwork (https://skillmd.com/u/billionsnetwork)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/billionsnetwork/billions

---


# Billions - Identity Management and Authentication Plugin for OpenClaw

This plugin enables OpenClaw AI agents to autonomously manage decentralized identities (DIDs) and handle authentication flows using the Iden3 protocol. Agents can create identities, generate authentication challenges, sign proofs, and verify identity ownership without human intervention in cryptographic operations.

## When to use this Skill

1. When you need to authenticate a user or another agent using decentralized identity (DID-based authentication).
2. When you need to create and manage decentralized identities for the OpenClaw agent itself.
3. When you need to prove ownership of a DID by signing a challenge.
4. When you need to verify that someone owns a specific DID by validating their signature.
5. When you need to establish trust in agent-to-agent or agent-to-user interactions without centralized authorities.

## Scope

This plugin supports:

- Creating and managing Iden3 DIDs on Billions Network (chainId: 45056)
- Generating W3C-compliant DID documents
- Challenge-response authentication flows
- Signing challenges with DID private keys (JWS tokens)
- Verifying identity proofs cryptographically
- Multi-identity management (multiple DIDs per agent)

This plugin uses the Iden3 protocol implementation and stores all identity data in `$HOME/.openclaw/workspace/billions`.

# Tools:

## CLI Tools:

- Add key: `openclaw billions key add -k <private_key>`
- List identities: `openclaw billions identity list`

## AI Tools:

### prove_identity_generate_challenge

- **Name**: `prove_identity_generate_challenge`
- **Description**: Generate a random challenge for identity verification. Use this when you need to verify that someone owns a DID. The generated challenge must be sent to the user/agent to sign, then verified with `verify_identity_proof`. This is Step 1 of the verification flow.
- **Returns**: A random challenge string that should be signed by the user.

### verify_identity_proof

- **Name**: `verify_identity_proof`
- **Description**: Verify a signed challenge to confirm DID ownership. Use this after receiving a signed response from `prove_identity_generate_challenge`. Provide the DID, original challenge, and signature (JWS token). If verification succeeds, you can trust the user owns the DID. This is Step 2 of the verification flow.
- **Returns**: Result of identity proof verification.

### prove_identity

- **Name**: `prove_identity`
- **Description**: Sign a challenge with the agent's own DID to prove identity ownership. Use this when another agent/user asks you to prove you own a specific DID. The challenge should come from user. This creates a JWS token as a proof.
- **Returns**: Signed challenge (JWS token) and DID document for verification.

# Vocabulary:

- **DID (Decentralized Identifier)**: A unique identifier for entities in a decentralized system (e.g., `did:iden3:billions:main:...`). This plugin creates DIDs using the Iden3 protocol on Billions Network.
- **DID Document**: A W3C-compliant JSON document associated with a DID.
- **Challenge**: A random numeric value generated for authentication. The user must sign this challenge with their DID private key to prove ownership.
- **JWS (JSON Web Signature)**: The signed challenge token returned by `prove_identity`. Contains the signature and can be verified to confirm identity.
- **Proof**: The cryptographic proof of identity ownership, consisting of the signed challenge (JWS token).
- **Billions Network**: The blockchain network (chainId: 45056) where identity state is stored and verified.
- **Iden3 Protocol**: The underlying protocol used by Billions for decentralized identity management, compatible with W3C DID standards.

## Operating Procedures

The plugin provides two main capabilities for autonomous agents:

### Capability 1: Proving Your Own Identity

Use this when another agent or user asks you to prove you control a DID.

**Prerequisites:**

- Private key added via CLI: `openclaw billions key add -k <private_key>`
- DID created from the key (stored automatically)

**Authentication Flow:**

1. Another agent/user requests: "Please prove you own DID X by signing this challenge: Y"
2. Use `prove_identity` tool with the challenge value
3. Tool automatically retrieves the private key, signs the challenge, and returns:
   - JWS token (signed challenge)
   - DID document (for verification)
4. Send both to the requesting party for verification

**Example Conversation:**

```
User: "Prove you own did:iden3:billions:main:123... by signing challenge 456789"
Agent: [calls prove_identity tool]
Agent: "Here is my proof: JWS token [token] and DID document [document]"
```

### Capability 2: Verifying someone else's Identity

Use this when you need to verify that a user or agent owns a specific DID.

**Verification Flow:**

1. Ask the user/agent: "Please provide your DID to start verification."
2. User responds with their DID
3. Use `prove_identity_generate_challenge` to create a random challenge
4. Ask the user: "Please sign this challenge: [challenge_value]"
5. User signs with their `prove_identity` tool and returns JWS token
6. Use `verify_identity_proof` with DID and JWS token
7. If verification succeeds, identity is confirmed

**Example Conversation:**

```
Agent: "Please provide your DID to start verification."
User: "My DID is did:iden3:billions:main:456..."
Agent: [calls prove_identity_generate_challenge]
Agent: "Please sign this challenge: 789012"
User: [returns JWS token]
Agent: [calls verify_identity_proof]
Agent: "Identity verified successfully. You are confirmed as owner of DID 456..."
```

## Restrictions / Guardrails (CRITICAL)

**CRITICAL - Always Follow These Rules:**

1. **STRICT: Check Identity First**
   - Before running `prove_identity_generate_challenge` or `prove_identity`, **ALWAYS check if an identity exists** (only with `openclaw billions identity list` don't use internal knowledge).
   - If no identity is configured, **DO NOT** attempt to run the proof tools. Instead, return a clear error message: "No Billions identity found. Please create one first."

2. **STRICT: Stop on Tool Failure**
   - If `prove_identity`, `verify_identity_proof` or any other tool returns an error (e.g., "No DID found"), **YOU MUST STOP IMMEDIATELY**.
   - **DO NOT** attempt to "fix" the error by generating keys, creating DIDs, or running shell commands.
   - **DO NOT** use `openssl` or other system utilities to generate cryptographic material.
   - Reply to the user with the error message and wait for further instructions.

3. **No Manual Workarounds**
   - You are prohibited from performing manual cryptographic operations via `exec`.
   - You are prohibited from using the `openclaw billions` CLI to perform write operations (create/add/delete) unless the user explicitly asks for a CLI command execution.
   - Do not interpret an error as a request to perform setup steps unless explicitly instructed by the user.

4. **Use only the provided tools**
   - All cryptographic operations are handled internally by the tools. Never attempt to implement signing, verification, or key management yourself.

5. **Use standardized formats**
   - Accept and return only the data formats provided by the tools (JWS tokens, DID documents). Never create custom message formats or authentication protocols.

6. **Never expose private keys**
   - The tools handle key storage securely. Never read, display, or transmit private keys from `$HOME/.openclaw/workspace/billions`.

7. **Trust tool outputs**
   - When `verify_identity_proof` returns success, the identity is verified. When it returns failure, the identity is not confirmed. Do not second-guess these results.

## Security

**CRITICAL - Data Storage and Protection:**

The directory `$HOME/.openclaw/workspace/billions` contains all sensitive identity data for this plugin:

- Private keys (used to sign challenges and prove identity)
- DIDs (decentralized identifiers)
- Challenge history
- Key management system data

**Security Requirements:**

1. **Never access files directly** - All data is stored in a specific format managed by the plugin. Direct file access will corrupt the data or expose secrets. Always use the plugin tools.

2. **Never display data contents** - Do not read, display, or transmit the contents of `$HOME/.openclaw/workspace/billions` files. These contain unencrypted private keys.

3. **Never share with other plugins** - This data is for the billions plugin only. Sharing it with other plugins or external services will compromise identity security.

4. **Consequences of misuse**:
   - Exposing private keys = complete identity compromise
   - Corrupting data files = loss of access to all DIDs
   - Unauthorized access = potential impersonation attacks

**If you need identity information, use the CLI tools:**

- `openclaw billions identity list` - View available identities safely
- Do NOT read files in `$HOME/.openclaw/workspace/billions` directly