## 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**:

**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**:

---

### generateChallenge.js

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

**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**:

**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**:

**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**:

**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:**

### 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:**

cd scripts && npm install && cd ..
# Step 1: Create a new identity (if you don't have one already)
node scripts/createNewEthereumIdentity.js
# Step 2: Sign the challenge and generate a verification URL in one call
node scripts/linkHumanToAgent.js --to <SENDER> --challenge '{"name": <AGENT_NAME>, "description": <SHORT_DESCRIPTION>}'

# 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...