@bankofbots/skill 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/SKILL.md +238 -28
  2. package/package.json +1 -1
  3. package/references/commands.md +78 -75
  4. package/references/errors.md +10 -12
  5. package/references/proofs.md +31 -19
  6. package/references/scoring.md +26 -13
package/SKILL.md CHANGED
@@ -8,46 +8,256 @@ description: >
8
8
  metadata: '{"openclaw":{"requires":{"env":["BOB_API_KEY","BOB_AGENT_ID"]},"optional":{"env":["BOB_API_URL"]},"primaryEnv":"BOB_API_KEY"}}'
9
9
  ---
10
10
 
11
- You are a BOB (Bank of Bots) agent. You use `bob`, the Bank of Bots CLI, to manage wallets, send BTC payments, and build your BOB Score through verified payment history.
11
+ ## Core concepts
12
12
 
13
- **Rails: `lightning` and `onchain` only. BTC only. All amounts in satoshis.**
13
+ Bank of Bots v0 is a non-custodial payment proof and trust layer. Agents submit cryptographic proofs of Bitcoin payments they made externally. Each proof builds credit history and raises their BOB Score — a 0–1000 reputation score that represents long-term financial trustworthiness.
14
14
 
15
- ## Setup
15
+ - **Agent**: An AI agent with its own identity and BOB Score
16
+ - **Payment Intent**: A structured outbound payment — quote routes, execute, optionally submit a proof
17
+ - **Payment Proof**: Cryptographic evidence of a BTC payment (onchain txid, Lightning payment hash, or preimage)
18
+ - **BOB Score**: 0–1000 reputation score derived from proof history, wallet binding, and social signals
19
+ - **Credit Event**: A scored action that changed the agent's BOB Score (proof submitted, wallet bound, etc.)
20
+ - **Wallet Binding**: Proof of ownership over an external EVM or Lightning wallet — a trust signal for BOB Score
21
+
22
+ ## Commands
23
+
24
+ ### Check your identity
25
+
26
+ ```bash
27
+ bob auth me
28
+ ```
29
+
30
+ Returns your role (agent or operator), identity details, and role-aware `next_actions`.
31
+
32
+ ### Agent management
16
33
 
17
34
  ```bash
18
- # Install: download bob binary from https://github.com/bankofbots/bob-cli/releases/latest
19
- # Required env: BOB_API_KEY, BOB_AGENT_ID
20
- # Optional env: BOB_API_URL (default: https://api.bankofbots.ai/api/v1)
21
- bob auth me # verify connection
22
- bob wallet list $BOB_AGENT_ID # check wallets and funding status
23
- bob agent credit $BOB_AGENT_ID # check BOB Score
35
+ # Create an agent
36
+ bob agent create --name <name>
37
+
38
+ # Get agent details
39
+ bob agent get <agent-id>
40
+
41
+ # List all agents
42
+ bob agent list
43
+
44
+ # Approve an agent
45
+ bob agent approve <agent-id>
24
46
  ```
25
47
 
26
- ## Core commands
48
+ ### Quote and execute payment intents
49
+
50
+ The intent workflow quotes routes before executing, giving visibility into fees, ETAs, and available rails.
27
51
 
28
52
  ```bash
29
- # Send BTC (one-shot: auto-quotes and executes)
30
- bob send $BOB_AGENT_ID <destination> --amount <sats>
53
+ # Quote routes for a BTC payment
54
+ bob intent quote <agent-id> --amount <sats> --destination-type raw --destination-ref <lnbc...|bc1...>
55
+
56
+ # Execute a quoted intent (uses best quote by default)
57
+ bob intent execute <agent-id> <intent-id> [--quote-id <id>]
31
58
 
32
- # Submit payment proof (builds BOB Score)
33
- bob intent submit-proof $BOB_AGENT_ID <intent-id> --preimage <hex> --proof-ref <payment-hash>
59
+ # Check intent status
60
+ bob intent get <agent-id> <intent-id>
34
61
 
35
- # Check score and history
36
- bob agent credit $BOB_AGENT_ID
37
- bob agent credit-events $BOB_AGENT_ID
62
+ # List recent intents
63
+ bob intent list <agent-id>
38
64
  ```
39
65
 
40
- ## Rules
66
+ | Flag | Description |
67
+ |---|---|
68
+ | `--amount` | Required. Amount in satoshis |
69
+ | `--destination-type` | `raw` or `bob_address` |
70
+ | `--destination-ref` | Lightning invoice, on-chain address, or `alias@bankofbots.ai` |
71
+ | `--priority` | `cheapest`, `fastest`, or `balanced` (default: balanced) |
72
+ | `--rail` | Pin to a specific rail: `lightning` or `onchain` |
73
+
74
+ ### Submit payment proofs
75
+
76
+ Proofs are the primary way to build credit history and increase BOB Score.
77
+
78
+ ```bash
79
+ # Submit an on-chain BTC proof
80
+ bob intent submit-proof <agent-id> <intent-id> --txid <txid>
81
+
82
+ # Submit a Lightning payment hash
83
+ bob intent submit-proof <agent-id> <intent-id> --payment-hash <hash>
84
+
85
+ # Submit a Lightning preimage (strongest confidence)
86
+ bob intent submit-proof <agent-id> <intent-id> --preimage <hex> --proof-ref <payment-hash>
87
+
88
+ # List proofs submitted for an intent
89
+ bob intent proofs <agent-id> <intent-id>
90
+ ```
91
+
92
+ **Proof confidence tiers** (strongest → weakest):
93
+ - `strong` — preimage verified (SHA256 matches payment hash)
94
+ - `medium` — payment hash verified
95
+ - `provisional` — on-chain tx detected, awaiting confirmations
96
+ - `low` — unverified
97
+
98
+ Proof responses include a `credit` object with `awarded`, `delta`, and `reason` so agents can track score impact.
99
+
100
+ ### Import historical BTC proofs
101
+
102
+ Build credit history from past payments you made before joining the network.
103
+
104
+ ```bash
105
+ bob agent credit-import <agent-id> \
106
+ --proof-type btc_onchain_tx \
107
+ --proof-ref <txid> \
108
+ --rail onchain \
109
+ --currency BTC \
110
+ --amount <sats> \
111
+ --direction outbound
112
+
113
+ # Also supports:
114
+ # --proof-type btc_lightning_payment_hash --proof-ref <hash>
115
+ # --proof-type btc_lightning_preimage --proof-ref <preimage>
116
+
117
+ # List imported historical proofs
118
+ bob agent credit-imports <agent-id> [--limit 50] [--offset 0]
119
+ ```
120
+
121
+ ### Check agent credit and BOB Score
122
+
123
+ ```bash
124
+ # View credit score, tier, and effective limits
125
+ bob agent credit <agent-id>
126
+
127
+ # View credit event timeline
128
+ bob agent credit-events <agent-id> [--limit 50] [--offset 0]
129
+ ```
130
+
131
+ ### BOB Score
132
+
133
+ ```bash
134
+ # View your operator score and signal breakdown
135
+ bob score me
136
+
137
+ # View signal-by-signal composition
138
+ bob score composition
139
+
140
+ # View public leaderboard
141
+ bob score leaderboard
142
+
143
+ # Toggle visibility of a specific signal
144
+ bob score signals --signal github --visible true
145
+ ```
146
+
147
+ **BOB Score tiers:**
148
+
149
+ | Tier | Threshold | Limit multiplier |
150
+ |---|---|---|
151
+ | Legendary | 925+ | — |
152
+ | Elite | 800+ | — |
153
+ | Trusted | 650+ | 1.5x |
154
+ | Established | 500+ | 1.2x |
155
+ | Verified | 400+ | 1.0x |
156
+ | New | 300+ | 1.0x |
157
+ | Unverified | 150+ | 0.6x |
158
+ | Blacklisted | 0+ | 0.6x |
159
+
160
+ **Trust signals that drive score:**
161
+ - Email (10 pts), Phone (10 pts), GitHub (20 pts), Twitter/X (20 pts)
162
+ - KYC/Identity (75 pts), Deposit (100 pts)
163
+ - EVM wallet binding (variable), Lightning wallet binding (variable)
164
+ - Payment proof history (1–10 pts per proof, by amount + confidence)
165
+
166
+ ### Bind a wallet (trust signal for BOB Score)
167
+
168
+ ```bash
169
+ # EVM wallet (MetaMask, Coinbase, etc.)
170
+ bob binding evm-challenge
171
+ bob binding evm-verify --address <0x...> --signature <sig>
172
+
173
+ # Lightning node
174
+ bob binding lightning-challenge <agent-id>
175
+ bob binding lightning-verify <agent-id> --node-pubkey <pubkey> --signature <sig>
176
+
177
+ # List bindings
178
+ bob binding list
179
+
180
+ # Remove a binding
181
+ bob binding delete <binding-id>
182
+ ```
183
+
184
+ ### Social signals
185
+
186
+ ```bash
187
+ # Link GitHub or Twitter/X for BOB Score trust signals
188
+ bob auth social --provider github
189
+ bob auth social --provider twitter
190
+ ```
191
+
192
+ ### Webhooks
193
+
194
+ ```bash
195
+ # Create a webhook for an agent
196
+ bob webhook create <agent-id> --url https://example.com/hook --events proof.verified,credit.updated
197
+
198
+ # List / get / update / delete
199
+ bob webhook list <agent-id>
200
+ bob webhook get <agent-id> <webhook-id>
201
+ bob webhook update <agent-id> <webhook-id> --active true
202
+ bob webhook delete <agent-id> <webhook-id>
203
+ ```
204
+
205
+ **v0 event types:** `proof.verified`, `proof.rejected`, `credit.updated`, `payment_intent.settled`, `payment_intent.failed`
206
+
207
+ ### Inbox
208
+
209
+ ```bash
210
+ # List inbox events (paginated)
211
+ bob inbox list <agent-id> [--limit 30] [--offset 0]
212
+
213
+ # Acknowledge an event
214
+ bob inbox ack <agent-id> <event-id>
215
+
216
+ # Pull recent agent events
217
+ bob inbox events <agent-id> [--limit 30]
218
+ ```
219
+
220
+ ### API keys
221
+
222
+ ```bash
223
+ bob api-key list
224
+ bob api-key create --name <label>
225
+ bob api-key revoke <key-id>
226
+ ```
227
+
228
+ ## Output format
229
+
230
+ Every command returns JSON with this structure:
231
+
232
+ ```json
233
+ {
234
+ "ok": true,
235
+ "command": "bob intent submit-proof",
236
+ "data": { ... },
237
+ "next_actions": [
238
+ {
239
+ "command": "bob agent credit <agent-id>",
240
+ "description": "Check updated BOB Score"
241
+ }
242
+ ]
243
+ }
244
+ ```
245
+
246
+ Always check `ok` before using `data`. When `ok` is false, `data.error` contains the error message and `next_actions` provides recovery suggestions.
247
+
248
+ ## Error recovery
41
249
 
42
- 1. **Always check `ok`** before using `data`. On failure, read `data.error` and follow `next_actions`.
43
- 2. **Kill switch**: If denied with kill switch reason, stop all transactions immediately. Do not retry.
44
- 3. **409 Conflict**: Do not retry — resource already exists. Inspect current state first.
45
- 4. **`tx record`** debits wallet balance — only run when wallet has sufficient funds.
46
- 5. **Never invent amounts, txids, or payment hashes.** Use only values returned by the API or provided by the user.
250
+ | Error | Recovery |
251
+ |---|---|
252
+ | `403 Forbidden` | Run `bob auth me` — API key may be invalid or agent not approved |
253
+ | `429 Too Many Requests` | Back off and retry; check `next_actions` for suggested wait |
254
+ | Proof verification failed | Use preimage instead of payment hash when available; confirm txid is settled |
255
+ | Challenge expired | Re-run the challenge command to get a fresh nonce |
256
+ | Claim code rejected | Generate a new one from the dashboard |
47
257
 
48
- ## Reference files
258
+ ## Important rules
49
259
 
50
- - [Full command reference](references/commands.md) — all commands and flags
51
- - [Proof submission](references/proofs.md) — proof types, submission flow, historical import
52
- - [BOB Score & tiers](references/scoring.md) — tiers, credit events, how to build score
53
- - [Error recovery](references/errors.md) — hard stops, recoverable errors, output format
260
+ 1. **Amounts** are always in satoshis for BTC.
261
+ 2. **Proofs are non-custodial** — Bank of Bots never holds your BTC. You pay externally and submit proof.
262
+ 3. **Preimage > hash > txid** — Use the strongest proof type available for the highest confidence tier and best credit outcome.
263
+ 4. **next_actions**: Every response includes suggested follow-up commands. Follow them to discover what to do next.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bankofbots/skill",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Bank of Bots skill file for AI agents (Claude Code, OpenClaw, and compatible platforms)",
5
5
  "main": "index.js",
6
6
  "files": [
package/references/commands.md CHANGED
@@ -3,7 +3,7 @@
3
3
  ## Identity
4
4
 
5
5
  ```bash
6
- bob auth me # your role, agent/operator ID, next_actions
6
+ bob auth me # your role, operator ID, next_actions
7
7
  bob config show # active api_url, platform, config file path
8
8
  bob config set api-url <url>
9
9
  bob config set platform <generic|openclaw|claude>
@@ -12,112 +12,115 @@ bob config set platform <generic|openclaw|claude>
12
12
  ## Agent
13
13
 
14
14
  ```bash
15
- bob agent get <agent-id> # details + wallets array with balances
16
- bob agent credit <agent-id> # BOB Score, tier, effective policy limits
15
+ bob agent create --name <name> # create a new agent
16
+ bob agent get <agent-id> # details, status, tags
17
+ bob agent list # list all agents (paginated)
18
+ bob agent approve <agent-id> # approve a pending agent
19
+ bob agent credit <agent-id> # BOB Score, tier, effective limits
17
20
  bob agent credit-events <agent-id> [--limit 50] [--offset 0]
18
- bob agent routing-profile <agent-id>
19
- bob agent routing-profile set <agent-id> \
20
- --cost-weight 0.6 --eta-weight 0.4 \
21
- --reliability-weight 0.2 --liquidity-weight 0.1 \
22
- --preferred-btc lightning,onchain
21
+ bob agent credit-import <agent-id> --proof-type <type> --proof-ref <ref> \
22
+ --rail <rail> --currency BTC --amount <sats> --direction outbound
23
+ bob agent credit-imports <agent-id> [--limit 50] [--offset 0]
23
24
  ```
24
25
 
25
- ## Wallets
26
+ ## Intent workflow (quote → inspect → execute)
26
27
 
27
28
  ```bash
28
- bob wallet list <agent-id> # balances, rails, status; includes bob_address
29
- bob wallet budget get <agent-id> --wallet-id <id>
30
- bob wallet budget set <agent-id> --wallet-id <id> --amount <sats>
31
- ```
32
-
33
- ## Sending (one-shot)
29
+ bob intent quote <agent-id> \
30
+ --amount <sats> \
31
+ --destination-type raw \
32
+ --destination-ref <lnbc...|bc1...>
34
33
 
35
- ```bash
36
- bob send <agent-id> <destination> --amount <sats>
34
+ bob intent execute <agent-id> <intent-id> [--quote-id <id>]
35
+ bob intent get <agent-id> <intent-id>
36
+ bob intent list <agent-id>
37
37
  ```
38
38
 
39
- Destination auto-detected: `jade@bankofbots.ai` → bob_address, `lnbc...` → Lightning, `bc1...` → onchain.
40
-
41
39
  | Flag | Description |
42
40
  |---|---|
43
- | `--amount` | Required. Satoshis |
44
- | `--priority` | cheapest, fastest, balanced (default: balanced) |
45
- | `--description` | Optional payment note |
46
- | `--max-fee` | Max fee in sats |
47
- | `--rail` | Pin to lightning or onchain |
48
- | `--destination-type` | Override: raw or bob_address |
41
+ | `--amount` | Required. Satoshis for BTC, gwei for ETH, lamports for SOL |
42
+ | `--destination-type` | `raw` or `bob_address` |
43
+ | `--destination-ref` | Lightning invoice, on-chain address, or `alias@bankofbots.ai` |
44
+ | `--priority` | `cheapest`, `fastest`, or `balanced` (default: balanced) |
45
+ | `--rail` | Pin to `lightning`, `onchain`, `ethereum`, `base`, or `solana` |
46
+ | `--currency` | `BTC` (default), `ETH`, `SOL` |
47
+ | `--max-fee` | Max fee in base units |
49
48
 
50
- ## Intent workflow (quote → inspect → execute)
49
+ ## Proof submission
51
50
 
52
51
  ```bash
53
- bob intent quote <agent-id> --amount <sats> --destination-type raw --destination-ref <dest>
54
- bob intent execute <agent-id> <intent-id> [--quote-id <id>]
55
- bob intent get <agent-id> <intent-id>
56
- bob intent list <agent-id>
57
- ```
52
+ # On-chain BTC
53
+ bob intent submit-proof <agent-id> <intent-id> --txid <txid>
58
54
 
59
- | Flag | Description |
60
- |---|---|
61
- | `--amount` | Required. Satoshis |
62
- | `--destination-type` | raw or bob_address |
63
- | `--destination-ref` | Lightning invoice, onchain address, or alias@bankofbots.ai |
64
- | `--priority` | cheapest, fastest, balanced |
65
- | `--execution-mode` | auto or pinned |
66
- | `--rail` | Pin to lightning or onchain |
67
- | `--wallet-id` | Pin to specific wallet |
68
- | `--max-fee` | Max fee in sats |
55
+ # Lightning payment hash
56
+ bob intent submit-proof <agent-id> <intent-id> --payment-hash <hash>
69
57
 
70
- ## Transactions
58
+ # Lightning preimage (strongest)
59
+ bob intent submit-proof <agent-id> <intent-id> \
60
+ --preimage <hex> --proof-ref <payment-hash>
61
+
62
+ # EVM or Solana
63
+ bob intent submit-proof <agent-id> <intent-id> \
64
+ --proof-type eth_onchain_tx --proof-ref <txhash> [--chain-id 0x1]
65
+ bob intent submit-proof <agent-id> <intent-id> \
66
+ --proof-type sol_onchain_tx --proof-ref <txsig>
67
+
68
+ bob intent proofs <agent-id> <intent-id> # list proofs for intent
69
+ ```
70
+
71
+ ## BOB Score
71
72
 
72
73
  ```bash
73
- bob tx record <agent-id> --amount <sats> --currency BTC [--rail lightning|onchain] [--endpoint <url>]
74
- bob tx list <agent-id> [--status complete] [--direction outbound] [--limit 10]
75
- bob tx transfer <from-agent-id> --to-agent-id <to-id> --amount <sats> --currency BTC
76
- bob tx transfers <agent-id>
77
- bob spend list <agent-id>
74
+ bob score me # operator BOB Score and signal breakdown
75
+ bob score composition # signal-by-signal composition
76
+ bob score leaderboard # public leaderboard
77
+ bob score signals --signal github --visible true
78
78
  ```
79
79
 
80
- `tx record` debits wallet balance — requires funded wallet.
80
+ ## Wallet binding (trust signals)
81
+
82
+ ```bash
83
+ # EVM wallet (MetaMask, Coinbase, etc.)
84
+ bob binding evm-challenge --address <0x...>
85
+ bob binding evm-verify --challenge-id <id> --address <0x...> --signature <sig> [--chain-id 0x1]
86
+
87
+ # Lightning node
88
+ bob binding lightning-challenge <agent-id>
89
+ bob binding lightning-verify <agent-id> --challenge-id <id> --signature <sig>
90
+ ```
81
91
 
82
- ## Policies
92
+ ## Social signals
83
93
 
84
94
  ```bash
85
- bob policy list <agent-id>
95
+ bob auth social --provider github
96
+ bob auth social --provider twitter
86
97
  ```
87
98
 
88
- ## Webhooks & events
99
+ ## Webhooks & inbox
89
100
 
90
101
  ```bash
91
- bob agent webhooks create <agent-id> --url <url> --events payment_intent.complete,payment.failed
92
- bob agent webhooks list <agent-id>
93
- bob agent webhooks get <agent-id> <webhook-id>
94
- bob agent webhooks update <agent-id> <webhook-id> --active true
95
- bob agent webhooks delete <agent-id> <webhook-id>
96
- bob agent events <agent-id> [--limit 30] [--offset 0]
102
+ bob webhook create <agent-id> --url <url> [--events proof.verified,credit.updated]
103
+ bob webhook list <agent-id>
104
+ bob webhook get <agent-id> <webhook-id>
105
+ bob webhook update <agent-id> <webhook-id> --active true
106
+ bob webhook delete <agent-id> <webhook-id>
107
+
108
+ bob inbox list <agent-id> [--limit 30] [--offset 0]
109
+ bob inbox ack <agent-id> <event-id>
110
+ bob inbox events <agent-id> [--limit 30]
97
111
  ```
98
112
 
99
- ## Service gates
113
+ ## API keys
100
114
 
101
115
  ```bash
102
- bob gate create <agent-id> --name "premium-api" --price 1000 --currency BTC
103
- bob gate list <agent-id>
104
- bob gate get <agent-id> <gate-id>
105
- bob gate update <agent-id> <gate-id> --status disabled
106
- bob gate unlock <owner-agent-id> <gate-id> --intent-id <intent-id>
107
- bob gate unlocks <agent-id> <gate-id>
108
- bob gate my-unlocks <agent-id>
109
- bob gate discover <agent-id>
116
+ bob api-key list
117
+ bob api-key create --name <label>
118
+ bob api-key revoke <key-id>
110
119
  ```
111
120
 
112
- ## Operator commands
121
+ ## Doctor / init
113
122
 
114
123
  ```bash
115
- bob operator credit summary
116
- bob operator credit refresh
117
- bob operator credit enforcement set --enabled=true
118
- bob address create --handle ops
119
- bob address list
120
- bob address add-endpoint <address-id> --currency BTC --rail lightning --destination-type raw --destination-ref <dest>
121
- bob address set-endpoint-status <address-id> <endpoint-id> --status disabled
122
- bob address resolve --address ops@bankofbots.ai --currency BTC
124
+ bob doctor # check config, connectivity, and agent status
125
+ bob init --code BOB-XXXX-XXXX # redeem claim code and set up credentials
123
126
  ```
package/references/errors.md CHANGED
@@ -6,27 +6,25 @@ Every failed command returns `ok: false` with `data.error` and `next_actions`. A
6
6
 
7
7
  | Error | Action |
8
8
  |---|---|
9
- | Kill switch active | **STOP all transactions immediately.** Run `bob policy list <agent-id>` to confirm. Do not retry until operator lifts the freeze. |
10
- | 403 Forbidden | Run `bob auth me`. Key may be invalid or agent not approved. |
11
- | Policy violation (tx denied) | Do not retry with same parameters. Read `data.error` — change amount, endpoint, or rail. |
9
+ | 403 Forbidden | Run `bob auth me`. API key invalid or agent not approved. |
10
+ | Proof ownership mismatch | Challenge may have expired — re-run the challenge command for a fresh nonce. |
12
11
 
13
12
  ## Recoverable errors
14
13
 
15
14
  | Error | Action |
16
15
  |---|---|
17
- | Insufficient balance | Run `bob wallet list <agent-id>` to check available funds. Wait for incoming payment or ask operator to fund. |
18
- | Spend/rate limit exceeded | Run `bob spend list <agent-id>` to see usage vs limits. Wait for window reset or request limit increase. |
19
- | 409 Conflict | Resource already exists. Do not retry — run `bob agent get <agent-id>` or `bob intent get` to confirm current state. |
20
- | Wallet not provisioned | Agent has no wallet for requested currency/rail. Contact operator to provision. |
21
- | Wallet not ready | Wallet exists but is pending. Run `bob wallet list <agent-id>` and wait for status=ready. |
22
- | Lightning invoice expired | Re-request a fresh invoice from the payee and retry. |
23
- | Proof already submitted | Duplicate proof ref — already counted. Check `bob agent credit-events`. |
16
+ | 429 Too Many Requests | Back off and retry. Check `next_actions` for suggested wait. |
17
+ | 409 Conflict | Resource already exists. Run `bob agent get` or `bob intent get` to confirm state. |
18
+ | Proof already submitted | Duplicate proof ref — already counted. Check `bob agent credit-events <agent-id>`. |
19
+ | Challenge expired | Re-run the binding challenge command (`bob binding evm-challenge` or `bob binding lightning-challenge`). |
20
+ | Claim code rejected | Generate a new code from the dashboard. |
21
+ | Proof verification failed | Use preimage instead of payment hash when available. Confirm tx is settled on-chain. |
24
22
 
25
23
  ## Output format
26
24
 
27
25
  ```json
28
26
  {
29
- "ok": true | false,
27
+ "ok": true,
30
28
  "command": "bob <subcommand>",
31
29
  "data": { ... },
32
30
  "next_actions": [
@@ -35,4 +33,4 @@ Every failed command returns `ok: false` with `data.error` and `next_actions`. A
35
33
  }
36
34
  ```
37
35
 
38
- `ok: false` → `data.error` has the reason. `next_actions` always present — execute them in order.
36
+ `ok: false` → `data.error` has the reason. Follow `next_actions` in order.
package/references/proofs.md CHANGED
@@ -1,29 +1,38 @@
1
1
  # BOB Score — Proof Submission
2
2
 
3
- Submitting payment proofs verifies settlement on-chain and awards BOB Score credit. Stronger proof types earn more credit.
3
+ Submitting payment proofs verifies settlement and awards BOB Score credit. Stronger proof types earn more credit.
4
4
 
5
- ## Proof types (strongest → weakest)
5
+ ## Proof types
6
6
 
7
- | Type | Command flag | What it proves |
8
- |---|---|---|
9
- | `btc_lightning_preimage` | `--preimage <hex> --proof-ref <payment-hash>` | SHA256(preimage) == payment hash — cryptographically irrefutable |
10
- | `btc_onchain_tx` | `--txid <txid>` | On-chain transaction confirmed |
11
- | `btc_lightning_payment_hash` | `--payment-hash <hash>` | Payment hash known (weaker — hash alone doesn't prove payment) |
7
+ | Type | Flag(s) | Confidence | What it proves |
8
+ |---|---|---|---|
9
+ | `btc_lightning_preimage` | `--preimage <hex> --proof-ref <hash>` | **strong** | SHA256(preimage) == payment hash — cryptographically irrefutable |
10
+ | `btc_lightning_payment_hash` | `--payment-hash <hash>` | **medium** | Payment hash observed on node |
11
+ | `btc_onchain_tx` | `--txid <txid>` | **provisional→strong** | On-chain tx confirmed (upgrades as confirmations accumulate) |
12
+ | `eth_onchain_tx` | `--proof-type eth_onchain_tx --proof-ref <txhash> [--chain-id 0x1]` | **medium→strong** | EVM on-chain tx (Ethereum mainnet or Base) |
13
+ | `base_onchain_tx` | `--proof-type base_onchain_tx --proof-ref <txhash>` | **medium→strong** | Base L2 on-chain tx |
14
+ | `sol_onchain_tx` | `--proof-type sol_onchain_tx --proof-ref <txsig>` | **medium→strong** | Solana on-chain tx |
12
15
 
13
16
  ## Submit proof against a payment intent
14
17
 
15
18
  ```bash
16
- # On-chain
19
+ # BTC on-chain
17
20
  bob intent submit-proof <agent-id> <intent-id> --txid <txid>
18
21
 
19
22
  # Lightning payment hash
20
23
  bob intent submit-proof <agent-id> <intent-id> --payment-hash <hash>
21
24
 
22
- # Lightning preimage (strongest — add invoice for amount verification)
25
+ # Lightning preimage (highest confidence)
23
26
  bob intent submit-proof <agent-id> <intent-id> \
24
- --preimage <hex> \
25
- --proof-ref <payment-hash> \
26
- [--invoice <lnbc...>]
27
+ --preimage <hex> --proof-ref <payment-hash>
28
+
29
+ # EVM on-chain (Ethereum mainnet)
30
+ bob intent submit-proof <agent-id> <intent-id> \
31
+ --proof-type eth_onchain_tx --proof-ref <0x...txhash> --chain-id 0x1
32
+
33
+ # Solana on-chain
34
+ bob intent submit-proof <agent-id> <intent-id> \
35
+ --proof-type sol_onchain_tx --proof-ref <txsig>
27
36
  ```
28
37
 
29
38
  ## Import historical proofs (credit building)
@@ -32,18 +41,21 @@ For payments that happened before BOB tracking was set up:
32
41
 
33
42
  ```bash
34
43
  bob agent credit-import <agent-id> \
35
- --preimage <hex> \
44
+ --proof-type btc_lightning_preimage \
36
45
  --proof-ref <payment-hash> \
46
+ --rail lightning \
47
+ --currency BTC \
37
48
  --amount <sats> \
38
- --direction inbound \
39
- --invoice <lnbc...>
49
+ --direction outbound
40
50
  ```
41
51
 
52
+ Supported `--proof-type` values: `btc_onchain_tx`, `btc_lightning_payment_hash`, `btc_lightning_preimage`, `eth_onchain_tx`, `base_onchain_tx`, `sol_onchain_tx`
53
+
42
54
  Historical imports are capped — they count toward score but cannot substitute for ongoing payment history.
43
55
 
44
56
  ## How proofs affect BOB Score
45
57
 
46
- - Verified proofs emit `payment.proof_imported.btc` credit events
47
- - Preimage proofs bound to a BoP (Bound Ownership Proof) attestation earn the highest confidence tier
48
- - Amount thresholds: floor is 1,000 sats; $10+ payments earn 2× credit delta; $100+ earn 3×
49
- - Duplicate proof refs are deduplicated — submitting the same txid/hash twice doesn't double-count
58
+ - Each verified proof emits a credit event with `awarded`, `delta`, and `reason`
59
+ - Amount thresholds: floor is 1,000 sats / 1,000,000 gwei / 1,000,000 lamports
60
+ - Preimage proofs earn the highest confidence tier
61
+ - Duplicate proof refs are deduplicated — same txid/hash twice doesn't double-count
package/references/scoring.md CHANGED
@@ -15,29 +15,42 @@
15
15
 
16
16
  New agents start at 350 (Verified tier). Tier multipliers only apply when credit enforcement is enabled by the operator.
17
17
 
18
+ ## Trust signals
19
+
20
+ | Signal | Points |
21
+ |---|---|
22
+ | Email verified | 10 |
23
+ | Phone verified | 10 |
24
+ | GitHub connected | 20 |
25
+ | Twitter/X connected | 20 |
26
+ | KYC/Identity verified | 75 |
27
+ | EVM wallet binding | up to 50 (based on wallet history) |
28
+ | Lightning node binding | variable |
29
+ | Payment proof (per proof) | 1–10 pts based on amount + confidence |
30
+
18
31
  ## Credit events
19
32
 
20
- Positive events:
33
+ Positive:
21
34
  - `agent.activated` +10 — first activation
22
- - `tx.completed` +1 — successful spend
23
- - `transfer.sent` / `transfer.received` +1 — agent-to-agent transfer
24
- - `payment.proof_imported.btc` — varies by proof type and amount
25
- - `wallet.funded` +1 — wallet received funds
35
+ - `payment.proof_verified` — varies by proof type and amount
36
+ - `payment.proof_imported` — historical import credit
26
37
 
27
- Negative events:
28
- - `tx.denied` −2 to −3 — policy violation or insufficient balance
29
- - `payment.denied` −2 — payment blocked
38
+ Negative:
39
+ - `payment.proof_rejected` — 0 delta; check `reason` field
30
40
 
31
41
  ## How to build score fast
32
42
 
33
- 1. **Submit payment proofs** — historical and ongoing Lightning/onchain proofs are the highest-signal path
34
- 2. **Complete transactions** — every successful spend adds credit
35
- 3. **Use preimage proofs** — strongest proof type, highest confidence tier
36
- 4. **Consistent counterparty diversity** — varied endpoints/recipients signals healthy economic activity
43
+ 1. **Submit payment proofs** — ongoing Lightning/onchain proofs are the highest-signal path
44
+ 2. **Use preimage proofs** — strongest proof type, highest confidence tier
45
+ 3. **Import historical proofs** — build credit from past payments
46
+ 4. **Bind a wallet** — EVM wallet with transaction history adds up to 50 pts
47
+ 5. **Connect social accounts** — GitHub (20 pts), Twitter/X (20 pts)
37
48
 
38
49
  ## Check your score
39
50
 
40
51
  ```bash
41
- bob agent credit <agent-id> # score, tier, multiplier, enforcement status
52
+ bob score me # operator score, signals, tier
53
+ bob score composition # signal-by-signal breakdown
54
+ bob agent credit <agent-id> # agent score, tier, multiplier, limits
42
55
  bob agent credit-events <agent-id> # full event timeline with deltas
43
56
  ```