https://github.com/taikoxyz/pico
State channel on Taiko for Agent payments
https://github.com/taikoxyz/pico
agent payment state-channel taiko usdc
Last synced: about 1 month ago
JSON representation
State channel on Taiko for Agent payments
- Host: GitHub
- URL: https://github.com/taikoxyz/pico
- Owner: taikoxyz
- License: mit
- Created: 2026-04-27T06:40:52.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-20T14:23:35.000Z (2 months ago)
- Last Synced: 2026-05-20T17:54:07.025Z (2 months ago)
- Topics: agent, payment, state-channel, taiko, usdc
- Language: TypeScript
- Homepage: https://pico.inferenceroom.ai
- Size: 2.07 MB
- Stars: 0
- Watchers: 0
- Forks: 2
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# pico
> Trustless **1-hop state channel network for micro-payments on Taiko L2**.
> v1 is an **AI-agent payments system**: the agent surface is the
> [`pico` CLI](./apps/cli/), not a browser wallet.
Inspired by Lightning's LSP model. Stablecoin (USDC) is the default v1 asset;
the on-chain contracts also accept any owner-allowlisted ERC-20 and native ETH
(`token == address(0)`). **No native token.
No governance. No bridges. No MCP / x402 association.**
> **New here?** Open [`docs/learning/index.html`](./docs/learning/index.html) for a tour of every
> component before diving into source code. Start with `00-big-picture.html` if you
> want intuition first.
## Why 1-hop
Lightning's full multi-hop topology is overkill for the workloads pico targets:
- AI agents paying agents
- Clients paying DVMs
- Streaming dust-sized payments to APIs
Multi-hop adds liquidity-routing complexity, locked HTLCs, and onion-routing overhead
without buying the marginal user anything when "1 hop through a hub" is plenty. pico
collapses the graph: every channel terminates at a hub, every payment is `client → hub →
recipient`. Hubs compete on liquidity, fees, and uptime — exactly like LSPs.
## Repository layout
```
apps/
cli/ pico CLI — the v1 agent runtime (pay, listen, channel ops)
hub/ Long-running hub service (Fastify + ws + sqlite/postgres)
watchtower/ Standalone fraud monitor that posts penalty txs
packages/
contracts/ Solidity 0.8.26 PaymentChannel + Adjudicator + HTLC (Foundry)
protocol/ Shared TS types, EIP-712 schemas, constants, Nostr event kinds
state-machine/ Pure-function channel state transitions (browser-safe)
sdk/ Client SDK with Signer interface (browser + Node, depends on viem)
dvm-adapter/ Nostr DVM payment helpers (Phase 2)
test-utils/ Anvil/forge fixtures, mock hubs, deterministic keys
e2e/ Cross-package end-to-end tests
docs/ Protocol spec, threat model, and per-phase plans
docs/learning/ Per-component HTML tutorials — start at docs/learning/index.html
```
## Quick start
```bash
pnpm install
pnpm build
pnpm typecheck
pnpm test
pnpm pico hello # smoke check; prints all package versions
forge build --root packages/contracts
```
## Quick start for an AI agent (v1 target)
```bash
pnpm install
pnpm pico keys init # encrypted hot key
pnpm pico channel open --hub https://hub.example --amount 25
pnpm pico pay --to 0xRecipient --amount 0.05 --json # one-shot payment
pnpm pico listen --hub https://hub.example & # receive payments
```
Any-language agents shell out to the CLI; non-TS callers parse the `--json` output.
## Direct peer channels (hub as relay)
The on-chain contract is a generic two-party channel, so two users can open a
channel **directly between themselves** with the hub acting only as an untrusted
message relay (not a party, no liquidity, no fee, no co-signing). Run a
relay-enabled hub (`HUB_ENABLE_RELAY=true`); then, sharing that relay URL:
```bash
# recipient: co-sign inbound peer payments
pnpm pico listen --peer --via ws://relay.example/ws &
# opener: open a direct channel, pay, and cooperatively close
pnpm pico channel open --peer 0xPeer --amount 25 --via ws://relay.example/ws
pnpm pico pay --invoice --peer --via ws://relay.example/ws
pnpm pico channel close --peer --via ws://relay.example/ws
```
See [`ARCHITECTURE.md`](./ARCHITECTURE.md) and
[`docs/learning/09-peer-channels.html`](./docs/learning/09-peer-channels.html)
for the data flow and trade-offs (each peer watches the chain itself; no
hub-side watchtower).
## Toolchain
| Concern | Tool |
|---------------------|-----------------------------------|
| Package manager | pnpm 9.x with workspaces |
| Monorepo runner | Turborepo 2.x |
| TypeScript | 5.5+ (strict, ES2022, bundler) |
| Solidity | Foundry, solc 0.8.26 |
| EVM client | viem 2.x |
| Tests (TS) | Vitest |
| Tests (Solidity) | forge test |
| Lint + format | Biome 1.x |
| Versioning | Changesets |
| Git hooks | lefthook |
| CI | GitHub Actions |
## Hard constraints
- No native token. No governance. No staking.
- No bridges. No wrapped assets.
- viem only — never ethers.
- pnpm only — never yarn or npm.
- Local Prometheus + structured logs only — no observability vendors.
## Status
Pre-GA staging. AI-audited (DeepSeek + multi-agent), with critical and high
code findings addressed or tracked. The main remaining launch gates are
operator-controlled: verify current owner-key custody, revoke/cold-store the
deployer key, publish the real PGP key, run restore/paging/security drills,
and complete the real-USDC mainnet smoke channel. Mainnet config gates
fail-fast on dev keys and unsigned envelopes
(`apps/{hub,watchtower}/src/config-validate.ts`); state-acceptance gates
(`packages/state-machine/src/admit.ts`) verify hub-supplied states before
the SDK persists them.
Production-readiness is summarized in
[`final_readiness_report.html`](./final_readiness_report.html) — the single
source of truth for design, implementation, test, and documentation
readiness. Live operational work is tracked on
[issue #21](https://github.com/taikoxyz/pico/issues/21).
## Documentation
- [`final_readiness_report.html`](./final_readiness_report.html) — **the
single source of truth** for production readiness (design, implementation,
tests, documentation). Re-generated per release-candidate tag.
- [Issue #21](https://github.com/taikoxyz/pico/issues/21) — master
production-readiness tracker. Sub-issues are categorized
(`code` / `test` / `gke` / `taiko-contract` / `docs` / `audit` / `ci`)
and prioritized (`high` / `medium` / `low`).
- [`docs/learning/index.html`](./docs/learning/index.html) — per-component
HTML tutorials, offline-readable.
- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — components, trust assumptions,
why 1-hop.
- [`docs/protocol-spec.md`](./docs/protocol-spec.md) — formal protocol spec.
- [`docs/threat-model.md`](./docs/threat-model.md) — adversaries and failure
modes.
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — coding standards & PR process.
- [`SECURITY.md`](./SECURITY.md) — disclosure policy.
## License
MIT — see [`LICENSE`](./LICENSE).