@iamnotdou/ccp 0.2.1 → 0.2.2

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 (2) hide show
  1. package/README.md +184 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,184 @@
1
+ # @iamnotdou/ccp
2
+
3
+ Containment Certificate Protocol — CLI and MCP server for AI agents on Hedera.
4
+
5
+ CCP lets AI agents prove they are economically safe to transact with. Instead of reputation (which fails for stochastic, ephemeral agents), CCP uses **agent-independent smart contract constraints** backed by **locked exogenous reserves** and **auditor stake-at-risk**.
6
+
7
+ The agent cannot modify its own cage. That is the point.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ npm install -g @iamnotdou/ccp
13
+ ```
14
+
15
+ ## MCP Server (for AI Agents)
16
+
17
+ The MCP server exposes 18 tools over Model Context Protocol. Only `AGENT_PRIVATE_KEY` is required.
18
+
19
+ ```json
20
+ {
21
+ "mcpServers": {
22
+ "ccp": {
23
+ "command": "npx",
24
+ "args": ["@iamnotdou/ccp", "mcp"],
25
+ "env": {
26
+ "AGENT_PRIVATE_KEY": "0x..."
27
+ }
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
33
+ Contract addresses, RPC, and HCS topic default to Hedera Testnet. No hosting required — the MCP server runs as a local child process.
34
+
35
+ ### Tools
36
+
37
+ #### Read (no key needed)
38
+
39
+ | Tool | Description |
40
+ |------|-------------|
41
+ | `ccp_status` | Full system overview: spending limits, reserve, balances, certificate |
42
+ | `ccp_addresses` | Contract addresses and network config |
43
+ | `ccp_cert_verify` | Verify agent meets containment requirements |
44
+ | `ccp_cert_get` | Get certificate details by hash |
45
+ | `ccp_cert_lookup` | Find active certificate for an agent address |
46
+ | `ccp_reserve_status` | Reserve balance, lock status, C2/C3 adequacy |
47
+ | `ccp_spending_status` | Spending config and period tracking |
48
+ | `ccp_auditor_status` | Auditor attestation count, stake, challenges |
49
+ | `ccp_auditor_audit` | Read-only containment audit |
50
+ | `ccp_challenge_get` | Challenge details by ID |
51
+ | `ccp_challenge_list` | List challenges for a certificate |
52
+ | `ccp_hcs_timeline` | HCS event timeline from Hedera Consensus Service |
53
+
54
+ #### Write (key required)
55
+
56
+ | Tool | Key | Description |
57
+ |------|-----|-------------|
58
+ | `ccp_spending_pay` | AGENT | Pay below $5k (agent-only signature) |
59
+ | `ccp_spending_pay_cosign` | AGENT + LEDGER | Pay $5k-$10k (Ledger co-sign) |
60
+ | `ccp_cert_publish` | OPERATOR + AUDITOR + LEDGER | Publish new certificate (full flow) |
61
+ | `ccp_cert_revoke` | OPERATOR | Revoke a certificate |
62
+ | `ccp_reserve_deposit` | OPERATOR | Deposit USDC into reserve vault |
63
+ | `ccp_reserve_lock` | OPERATOR | Lock reserve for N days |
64
+
65
+ Missing keys return `{ "error": "KEY_NOT_CONFIGURED" }` — no crash.
66
+
67
+ ### Agent Workflow
68
+
69
+ ```
70
+ 1. ccp_status → "where am I?"
71
+ 2. ccp_cert_verify → "am I trusted?"
72
+ 3. ccp_spending_status → "how much can I spend?"
73
+ 4. ccp_spending_pay → "pay" (< $5k)
74
+ 5. ccp_hcs_timeline → "what happened?"
75
+ ```
76
+
77
+ ### Spending Rules
78
+
79
+ | Amount | Signature | Tool |
80
+ |--------|-----------|------|
81
+ | $0 - $5,000 | Agent only | `ccp_spending_pay` |
82
+ | $5,001 - $10,000 | Agent + Ledger | `ccp_spending_pay_cosign` |
83
+ | > $10,000 | BLOCKED | Hard limit, cannot be bypassed |
84
+ | Period > $50,000 | BLOCKED | Resets after 24h |
85
+
86
+ These limits are enforced by smart contracts. Even with Ledger co-signature, the agent cannot exceed them.
87
+
88
+ ## CLI
89
+
90
+ ```bash
91
+ ccp status # system overview
92
+ ccp cert:verify <agentAddress> # verify containment
93
+ ccp cert:get <certHash> # certificate details
94
+ ccp cert:lookup <agentAddress> # find active cert
95
+ ccp cert:publish # publish new cert
96
+ ccp cert:revoke <certHash> # revoke cert
97
+ ccp reserve:status # reserve vault info
98
+ ccp reserve:deposit <amount> # deposit USDC
99
+ ccp reserve:lock <days> # lock reserve
100
+ ccp spending:status # spending limits
101
+ ccp spending:pay <to> <amount> # pay (agent-only)
102
+ ccp spending:pay:cosign <to> <amount> # pay (Ledger co-sign)
103
+ ccp auditor:status # auditor record
104
+ ccp auditor:audit # containment audit
105
+ ccp challenge:get <id> # challenge details
106
+ ccp challenge:list <certHash> # challenges for cert
107
+ ccp hcs:timeline # event timeline
108
+ ccp addresses # contract addresses
109
+ ccp actors # actor addresses
110
+ ccp help # help
111
+ ```
112
+
113
+ ## Contracts (Hedera Testnet)
114
+
115
+ | Contract | Address |
116
+ |----------|---------|
117
+ | CCPRegistry | `0x776CAbA2d5E63F96358f1624976D6Aaa6b780ed1` |
118
+ | SpendingLimit | `0x281Feb02bb3AA41d3A75E24a06A1f142eEEA5C85` |
119
+ | ReserveVault | `0xb2fFaf44Ae415b0e1dFc99c8E07dfDE2a5369Aa6` |
120
+ | AuditorStaking | `0xe786eB0F88b8A30e0ABf4C634fc414084b2134eC` |
121
+ | FeeEscrow | `0xe619F278352B4eED4465a176Df0B2A2F2CAf3557` |
122
+ | ChallengeManager | `0x6238a4f9ad158dA64a4478FE64Ba0416b176cFC7` |
123
+ | HCS Topic | `0.0.8510266` |
124
+
125
+ Chain ID: 296 | RPC: `https://testnet.hashio.io/api`
126
+
127
+ ## How CCP Works
128
+
129
+ ```
130
+ ┌─────────────────────────────────────────────┐
131
+ │ CONTAINMENT CERTIFICATE │
132
+ ├─────────────────────────────────────────────┤
133
+ │ │
134
+ │ ┌──────────────┐ ┌──────────┐ ┌─────────┐ │
135
+ │ │ CONTAINMENT │ │ RESERVE │ │ AUDIT │ │
136
+ │ │ │ │ │ │ │ │
137
+ │ │ SpendingLimit│ │ $150k │ │ Auditor │ │
138
+ │ │ • $10k/tx │ │ USDC │ │ staked │ │
139
+ │ │ • $50k/day │ │ locked │ │ $13.5k │ │
140
+ │ │ • Ledger │ │ 3x ratio │ │ at risk │ │
141
+ │ │ cosign │ │ │ │ │ │
142
+ │ └──────────────┘ └──────────┘ └─────────┘ │
143
+ │ │
144
+ │ Agent-independent. The cage holds because │
145
+ │ the agent cannot modify it. │
146
+ │ │
147
+ └─────────────────────────────────────────────┘
148
+ ```
149
+
150
+ **Three layers of trust:**
151
+ 1. **Containment** — Smart contract spending limits + Ledger co-signing. Agent-independent.
152
+ 2. **Reserve** — $150k USDC locked on-chain. Exogenous, verifiable, non-recoverable during cert validity.
153
+ 3. **Auditor stake** — $13.5k at risk. Slashed if attestation proven false (30% to challenger, 50% to verifiers, 20% burned).
154
+
155
+ ## Env Variables
156
+
157
+ Only `AGENT_PRIVATE_KEY` is required. Everything else has Hedera Testnet defaults.
158
+
159
+ | Variable | Default | Required |
160
+ |----------|---------|----------|
161
+ | `AGENT_PRIVATE_KEY` | — | Yes (for write ops) |
162
+ | `OPERATOR_PRIVATE_KEY` | — | For cert/reserve management |
163
+ | `AUDITOR_PRIVATE_KEY` | — | For attestation |
164
+ | `LEDGER_PRIVATE_KEY` | — | For co-signed payments |
165
+ | `HEDERA_RPC_URL` | `https://testnet.hashio.io/api` | No |
166
+ | `HEDERA_CHAIN_ID` | `296` | No |
167
+ | `HCS_TOPIC_ID` | `0.0.8510266` | No |
168
+ | `REGISTRY_ADDRESS` | Testnet default | No |
169
+ | `RESERVE_VAULT_ADDRESS` | Testnet default | No |
170
+ | `SPENDING_LIMIT_ADDRESS` | Testnet default | No |
171
+ | `AUDITOR_STAKING_ADDRESS` | Testnet default | No |
172
+ | `FEE_ESCROW_ADDRESS` | Testnet default | No |
173
+ | `CHALLENGE_MANAGER_ADDRESS` | Testnet default | No |
174
+ | `USDC_ADDRESS` | Testnet default | No |
175
+
176
+ ## Links
177
+
178
+ - [Documentation](https://ccp-docs.vercel.app)
179
+ - [AI Agent Integration Guide](https://ccp-docs.vercel.app/docs/integrations/ai-agents)
180
+ - [GitHub](https://github.com/iamnotdou/ccp)
181
+
182
+ ## License
183
+
184
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iamnotdou/ccp",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "CCP — Containment Certificate Protocol CLI. Issue, verify, and enforce bounded-loss certificates for AI agents on Hedera.",
5
5
  "type": "module",
6
6
  "bin": {