Initial Setup (Run after installation)#

Before using this skill for the first time, you must execute:

bash

cd scripts && npm install
node createNewEthereumIdentity.js
node linkHumanToAgent.js --to <sender> --challenge <challenge_value>

When to use this Skill#

Lets AI agents create and manage their own identities on the Billions Network, and link those identities to a human owner.

1. When you need to link your agent identity to an owner.
2. When you need sign a challenge.
3. When you need link a human to the agent's DID.
4. When you need to verify a signature to confirm identity ownership.
5. When use shared JWT tokens for authentication.
6. When you need to create and manage decentralized identities.

Scope#

All identity data is stored in $HOME/.openclaw/billions for compatibility with the OpenClaw plugin.

Scripts:#

createNewEthereumIdentity.js#

Command: node scripts/createNewEthereumIdentity.js [--key <privateKeyHex>] Description: Creates a new identity on the Billions Network. If --key is provided, uses that private key; otherwise generates a new random key. The created identity is automatically set as default. Usage Examples:

bash

# Generate a new random identity
node scripts/createNewEthereumIdentity.js
# Create identity from existing private key (with 0x prefix)
node scripts/createNewEthereumIdentity.js --key 0x1234567890abcdef...
# Create identity from existing private key (without 0x prefix)
node scripts/createNewEthereumIdentity.js --key 1234567890abcdef...

Output: DID string (e.g., did:iden3:billions:main:2VmAk7fGHQP5FN2jZ8X9Y3K4W6L1M...)

---

getIdentities.js#

Command: node scripts/getIdentities.js Description: Lists all DID identities stored locally. Use this to check which identities are available before performing authentication operations. Usage Example:

bash

node scripts/getIdentities.js

Output: JSON array of identity entries

json

[
  {
    "did": "did:iden3:billions:main:2VmAk...",
    "publicKeyHex": "0x04abc123...",
    "isDefault": true
  }
]

---

generateChallenge.js#

Command: node scripts/generateChallenge.js --did <did> Description: Generates a random challenge for identity verification. Usage Example:

bash

node scripts/generateChallenge.js --did did:iden3:billions:main:2VmAk...

Output: Challenge string (random number as string, e.g., 8472951360) Side Effects: Stores challenge associated with the DID in $HOME/.openclaw/billions/challenges.json

---

signChallenge.js#

Command: node scripts/signChallenge.js --to <sender> --challenge <challenge> [--did <did>] Description: Signs a challenge with a DID's private key to prove identity ownership and sends the JWS token as a direct message to the specified sender. Use this when you need to prove you own a specific DID. Arguments:

• --to - (required) The message sender identifier, passed as --target to openclaw message send
• --challenge - (required) Challenge to sign
• --did - (optional) The DID of the attestation recipient; uses the default DID if omitted

Usage Examples:

bash

# Sign with default DID and send to sender
node scripts/signChallenge.js --to <sender> --challenge 8472951360

Output: {"success":true}

linkHumanToAgent.js#

Command: node scripts/linkHumanToAgent.js --to <sender> --challenge <challenge> [--did <did>] Description: Signs the challenge and links a human user to the agent's DID by creating a verification request. Response will be sent as a direct message to the specified sender. Arguments:

• --to - (required) The message sender identifier, passed as --target to openclaw message send
• --challenge - (required) Challenge to sign
• --did - (optional) The DID of the attestation recipient; uses the default DID if omitted

Usage Example:

bash

node scripts/linkHumanToAgent.js --to <sender> --challenge '{"name": "MyAgent", "description": "AI persona"}'

Output: {"success":true}

---

verifySignature.js#

Command: node scripts/verifySignature.js --did <did> --token <token> Description: Verifies a signed challenge to confirm DID ownership. Usage Example:

bash

node scripts/verifySignature.js --did did:iden3:billions:main:2VmAk... --token eyJhbGciOiJFUzI1NkstUi...

Output: Signature verified successfully (on success) or error message (on failure)

---

Restrictions / Guardrails (CRITICAL)#

CRITICAL - Always Follow These Rules:

1. STRICT: Check Identity First
   • Before running linkHumanToAgent.js or signChallenge.js, ALWAYS check if an identity exists: node scripts/getIdentities.js
   • If no identity is configured, DO NOT attempt to link identities. Instead, create an identity first with createNewEthereumIdentity.js.
2. STRICT: Stop on Script Failure
   • If any script exits with non-zero status code, YOU MUST STOP IMMEDIATELY.
   • Check stderr output for error messages.
   • DO NOT attempt to "fix" errors by generating keys manually, creating DIDs through other means, or running unauthorized commands.
   • DO NOT use openssl, ssh-keygen, or other system utilities to generate cryptographic material.
3. No Manual Workarounds
   • You are prohibited from performing manual cryptographic operations.
   • You are prohibited from directly manipulating files in $HOME/.openclaw/billions.
   • Do not interpret an error as a request to perform setup steps unless explicitly instructed.

---

Security#

CRITICAL - Data Storage and Protection:

The directory $HOME/.openclaw/billions contains all sensitive identity data:

• kms.json - CRITICAL: Contains unencrypted private keys
• defaultDid.json - DID identifiers and public keys
• challenges.json - Authentication challenges history
• credentials.json - Verifiable credentials
• identities.json - Identity metadata
• profiles.json - Profile data

Examples#

Link Your Agent Identity to Owner#

Linking Flow:

1. Another agent/user requests: "Please link your agent identity to me."

2. Use node scripts/getIdentities.js to check if you have an identity configured

   • If no identity, run node scripts/createNewEthereumIdentity.js to create one.

3. Use node scripts/linkHumanToAgent.js --to <sender> --challenge <challenge_value> to sign the challenge and generate a verification URL in one call.

   • The --to value is the message sender (the caller's identifier).
   • If caller provides specific challenge, use that.
   • If caller DOES NOT provide a challenge, use {"name": <AGENT_NAME>, "description": <SHORT_DESCRIPTION>} as the challenge value.

4. Return the result to the caller.

Example Conversation:

text

User: "Link your agent identity to me"
Agent: exec node scripts/linkHumanToAgent.js --to <sender> --challenge <challenge_value>

Verifying someone else's Identity#

Verification Flow:

1. Ask the user/agent: "Please provide your DID to start verification."
2. User responds with their <user_did>.
3. Use node scripts/generateChallenge.js --did <user_did> to create a <challenge_value>.
4. Ask the user: "Please sign this challenge: <challenge_value>"
5. User signs and returns <user_token>.
6. Use node scripts/verifySignature.js --did <user_did> --token <user_token> to verify the signature
7. If verification succeeds, identity is confirmed

Example Conversation:

text

Agent: "Please provide your DID to start verification."
User: "My DID is <user_did>"
Agent: exec node scripts/generateChallenge.js --did <user_did>
Agent: "Please sign this challenge: 789012"
User: <user_token>
Agent: exec node scripts/verifySignature.js --token <user_token> --did <user_did>
Agent: "Identity verified successfully. You are confirmed as owner of DID <user_did>."