-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathindex.html
More file actions
340 lines (329 loc) · 12.3 KB
/
Copy pathindex.html
File metadata and controls
340 lines (329 loc) · 12.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>pico · learning · index</title>
<style>
:root {
--ink: #1d1d1b;
--ink-soft: #4a4a48;
--paper: #fbfaf6;
--paper-warm: #f4efe6;
--rule: #d8d3c7;
--rule-soft: #ece7db;
--accent: #b3185f;
--accent-soft: #f1d9e6;
--code-bg: #efece4;
}
* { box-sizing: border-box; }
html { background: var(--paper); color: var(--ink); }
body {
margin: 0;
font-family: "Charter", "Iowan Old Style", "Source Serif Pro", Georgia, serif;
font-size: 17px;
line-height: 1.6;
-webkit-font-smoothing: antialiased;
}
.wrap { max-width: 780px; margin: 0 auto; padding: 56px 28px 96px; }
.topnav {
font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
font-size: 12.5px;
color: var(--ink-soft);
text-transform: uppercase;
letter-spacing: 0.1em;
border-bottom: 1px solid var(--rule);
padding-bottom: 14px;
margin-bottom: 48px;
display: flex;
justify-content: space-between;
align-items: baseline;
}
.topnav a { color: var(--ink-soft); text-decoration: none; border-bottom: 1px dashed transparent; }
.topnav a:hover { color: var(--accent); border-bottom-color: var(--accent); }
h1 {
font-size: 38px;
line-height: 1.15;
margin: 0 0 6px 0;
letter-spacing: -0.01em;
}
h1 .accent { color: var(--accent); }
.subtitle {
font-style: italic;
color: var(--ink-soft);
margin: 0 0 36px 0;
font-size: 18px;
}
h2 {
font-size: 22px;
margin: 48px 0 12px;
letter-spacing: -0.005em;
}
h3 {
font-size: 18px;
margin: 28px 0 8px;
}
p { margin: 0 0 16px; }
a { color: var(--accent); text-decoration: none; border-bottom: 1px solid var(--accent-soft); }
a:hover { border-bottom-color: var(--accent); }
code {
font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
font-size: 0.9em;
background: var(--code-bg);
padding: 1px 6px;
border-radius: 3px;
}
pre {
font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
font-size: 13.5px;
line-height: 1.55;
background: var(--code-bg);
border: 1px solid var(--rule);
border-radius: 6px;
padding: 14px 18px;
overflow-x: auto;
}
pre code { background: none; padding: 0; }
.toc {
list-style: none;
padding: 0;
margin: 18px 0 0;
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 12px;
}
.toc li {
border: 1px solid var(--rule);
border-radius: 6px;
padding: 14px 16px;
background: var(--paper);
}
.toc li:hover { border-color: var(--accent); background: var(--accent-soft); }
.toc a {
border: none;
color: var(--ink);
display: block;
}
.toc-num {
font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.12em;
color: var(--accent);
display: block;
margin-bottom: 4px;
}
.toc-title { font-weight: 600; }
.toc-blurb {
font-size: 14.5px;
color: var(--ink-soft);
margin-top: 4px;
font-style: italic;
}
table {
border-collapse: collapse;
width: 100%;
margin: 18px 0 30px;
font-size: 15.5px;
}
th, td {
text-align: left;
padding: 8px 10px;
border-bottom: 1px solid var(--rule-soft);
vertical-align: top;
}
th {
background: var(--paper-warm);
font-weight: 600;
border-bottom: 1px solid var(--rule);
}
td:first-child {
font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
font-size: 13px;
width: 32%;
white-space: nowrap;
color: var(--accent);
}
.note {
border-left: 3px solid var(--accent);
background: var(--accent-soft);
padding: 12px 18px;
margin: 18px 0;
font-size: 15.5px;
}
.footer {
margin-top: 80px;
padding-top: 18px;
border-top: 1px solid var(--rule);
font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
font-size: 12px;
color: var(--ink-soft);
text-transform: uppercase;
letter-spacing: 0.1em;
}
</style>
</head>
<body>
<div class="wrap">
<nav class="topnav">
<span>pico · learning</span>
<span><a href="../README.md">⤺ repo readme</a></span>
</nav>
<h1>pico <span class="accent">learning</span></h1>
<p class="subtitle">A component-by-component tour of a 1-hop state channel network for AI agents on Taiko L2.</p>
<p><strong>pico</strong> is a payments system designed for AI agents to pay each other for work — API calls, model inference, data, anything that can be priced per request. It uses <em>state channels</em>: a 2-of-2 escrow contract on Taiko, with all the actual payments happening off-chain via signed messages. On-chain you only ever see the channel <em>opening</em>, the channel <em>closing</em>, and (rarely) a <em>dispute</em>.</p>
<p>This folder is the friendly tour: open <a href="./00-big-picture.html">00-big-picture.html</a> first if you want intuition before structure, or click through the components in order if you'd rather build the picture from the bottom up. Every page is a single self-contained file — no JavaScript, no internet required.</p>
<h2>Reading order</h2>
<ol class="toc">
<li><a href="./00-big-picture.html">
<span class="toc-num">00 · story</span>
<span class="toc-title">Big picture</span>
<div class="toc-blurb">Alice pays Bob via the hub; the hub cheats; the watchtower wins. The whole flow as a story.</div>
</a></li>
<li><a href="./01-contracts.html">
<span class="toc-num">01 · packages/contracts</span>
<span class="toc-title">Contracts</span>
<div class="toc-blurb">PaymentChannel.sol, Adjudicator.sol, HTLC.sol — the trustless core on Taiko mainnet.</div>
</a></li>
<li><a href="./02-protocol.html">
<span class="toc-num">02 · packages/protocol</span>
<span class="toc-title">Protocol</span>
<div class="toc-blurb">The wire format. EIP-712 schemas, constants, type definitions every package shares.</div>
</a></li>
<li><a href="./03-state-machine.html">
<span class="toc-num">03 · packages/state-machine</span>
<span class="toc-title">State machine</span>
<div class="toc-blurb">Pure functions: validateUpdate, applyUpdate, signing, htlcsRoot. The brains.</div>
</a></li>
<li><a href="./04-sdk.html">
<span class="toc-num">04 · packages/sdk</span>
<span class="toc-title">SDK</span>
<div class="toc-blurb">ChannelClient, the Signer interface, transport, storage. The library agents call.</div>
</a></li>
<li><a href="./05-hub.html">
<span class="toc-num">05 · apps/hub</span>
<span class="toc-title">Hub</span>
<div class="toc-blurb">The router. Holds channels with everyone, forwards HTLCs, watches the chain.</div>
</a></li>
<li><a href="./06-watchtower.html">
<span class="toc-num">06 · apps/watchtower</span>
<span class="toc-title">Watchtower</span>
<div class="toc-blurb">The bodyguard. Catches stale-state submissions and slashes the cheater.</div>
</a></li>
<li><a href="./07-agent-runtime.html">
<span class="toc-num">07 · apps/cli</span>
<span class="toc-title">Agent runtime</span>
<div class="toc-blurb">The CLI. pico pay, pico listen, the encrypted hot key file. The v1 agent surface.</div>
</a></li>
<li><a href="./09-peer-channels.html">
<span class="toc-num">09 · direct peer channels</span>
<span class="toc-title">Peer channels</span>
<div class="toc-blurb">Two users open a channel between themselves; the hub only relays messages. Hub-less by design.</div>
</a></li>
<li><a href="./08-e2e.html">
<span class="toc-num">08 · e2e/</span>
<span class="toc-title">End-to-end tests</span>
<div class="toc-blurb">Whole-stack scenarios run against an anvil fork. The proof everything fits together.</div>
</a></li>
</ol>
<h2>Where to start</h2>
<p>Pick the entry that matches what you want to do today.</p>
<table>
<tr><th>If you want to…</th><th>Open this</th></tr>
<tr>
<td>Get intuition before any code</td>
<td><a href="./00-big-picture.html">00-big-picture.html</a></td>
</tr>
<tr>
<td>Understand the on-chain trust core</td>
<td><a href="./01-contracts.html">01-contracts.html</a></td>
</tr>
<tr>
<td>Read off-chain mechanics carefully</td>
<td><a href="./03-state-machine.html">03-state-machine.html</a></td>
</tr>
<tr>
<td>Build an agent that pays through the network</td>
<td><a href="./07-agent-runtime.html">07-agent-runtime.html</a></td>
</tr>
<tr>
<td>Run a hub or watchtower</td>
<td><a href="./05-hub.html">05-hub.html</a> · <a href="./06-watchtower.html">06-watchtower.html</a></td>
</tr>
<tr>
<td>Verify the whole thing works</td>
<td><a href="./08-e2e.html">08-e2e.html</a></td>
</tr>
</table>
<h2 id="glossary">Glossary</h2>
<p>Linked from every component page. Skim these once and the rest of the tour reads cleanly.</p>
<table>
<tr><th>Term</th><th>Meaning</th></tr>
<tr>
<td>channel</td>
<td>A 2-of-2 escrow on-chain between two parties (typically agent + hub). Funds are deposited once on open; balances move off-chain via signed updates.</td>
</tr>
<tr>
<td>state</td>
<td>A snapshot of a channel: <code>(balanceA, balanceB, htlcs[], version)</code>, signed by both parties. Versions only go up.</td>
</tr>
<tr>
<td>cooperative close</td>
<td>Both parties sign a final state and settle in one tx. The happy path.</td>
</tr>
<tr>
<td>unilateral close</td>
<td>One party (e.g., the hub disappeared) posts the latest state they have on-chain. Opens a <em>dispute window</em>.</td>
</tr>
<tr>
<td>dispute window</td>
<td>A fixed delay (24h in v1) before a unilaterally-posted state becomes final, giving the counterparty time to challenge with a newer signed state.</td>
</tr>
<tr>
<td>HTLC</td>
<td>Hash-Time-Locked Contract — a conditional payment: "$X is locked. Whoever reveals the preimage of hash H before time T claims it; otherwise it refunds."</td>
</tr>
<tr>
<td>watchtower</td>
<td>A bot that watches the chain for fraudulent old-state submissions and posts a counter-state before the dispute window closes.</td>
</tr>
<tr>
<td>EIP-712</td>
<td>Ethereum's typed-data signing standard. Channel states are signed as EIP-712 typed data so the digest a contract verifies matches what was signed off-chain.</td>
</tr>
<tr>
<td>1-hop routing</td>
<td>Payments flow <code>agent → hub → recipient</code> via two paired HTLCs. No multi-hop, no graph gossip.</td>
</tr>
<tr>
<td>hub</td>
<td>A long-running operator that holds channels with many users and routes payments. Analogous to a Lightning LSP.</td>
</tr>
<tr>
<td>hot wallet</td>
<td>A private key on a server. Convenient, capped at low balance.</td>
</tr>
<tr>
<td>Signer interface</td>
<td>The SDK abstraction over key custody. v1 backend = encrypted hot key file. Future backends: KMS, Turnkey, Nitro Enclave, EIP-7702 delegation.</td>
</tr>
<tr>
<td><code>pico listen</code></td>
<td>A long-running CLI subcommand for receivers. Holds a WebSocket session to the hub, accepts inbound HTLCs, reveals preimages.</td>
</tr>
<tr>
<td>encrypted hot key file</td>
<td>The on-disk key store the v1 Signer reads. Passphrase-derived (scrypt) key, sealed with XSalsa20-Poly1305. Permissions 0600.</td>
</tr>
<tr>
<td>litestream</td>
<td>A tool that continuously streams a SQLite DB to S3-compatible storage for backup and point-in-time restore.</td>
</tr>
</table>
<h2>What v1 deliberately does <em>not</em> include</h2>
<p>For honesty: the dogfood scope is narrow on purpose. The wallet UI for humans, ERC-8004 agent-identity registration, EIP-7702 / 4337 delegation, TEE / KMS Signer backends, multi-hop routing, ETH (non-USDC) support, and the DVM / Nostr discovery layer are all <strong>Phase 2</strong>. The project explicitly does not associate with MCP or x402; if those ecosystems want to consume pico, an external adapter can wrap the CLI.</p>
<div class="note">If you came here to learn before working on the codebase, follow the reading order. If you came here because you'll be running the system, jump to <a href="./07-agent-runtime.html">07-agent-runtime.html</a> and treat the rest as reference.</div>
<div class="footer">pico · learning · v0.1 · self-contained · open offline</div>
</div>
</body>
</html>