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, 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 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 <cmd> 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

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)

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:

# 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-invoice> --peer --via ws://relay.example/ws
pnpm pico channel close <channelId> --peer --via ws://relay.example/ws

See ARCHITECTURE.md and 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 — the single source of truth for design, implementation, test, and documentation readiness. Live operational work is tracked on issue #21.

Documentation

• final_readiness_report.html — the single source of truth for production readiness (design, implementation, tests, documentation). Re-generated per release-candidate tag.
• Issue #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 — per-component HTML tutorials, offline-readable.
• ARCHITECTURE.md — components, trust assumptions, why 1-hop.
• docs/protocol-spec.md — formal protocol spec.
• docs/threat-model.md — adversaries and failure modes.
• CONTRIBUTING.md — coding standards & PR process.
• SECURITY.md — disclosure policy.

License

MIT — see LICENSE.