chaincommons

package module
v0.0.0-...-caddeb3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: MIT Imports: 0 Imported by: 0

README

chain-commons

Shared chain-glue Go library for the livepeer-modules-project monorepo.

Provides the Ethereum/Arbitrum interaction primitives that payment-daemon, service-registry-daemon, and protocol-daemon consume:

  • Multi-RPC failover — primary/backup endpoint routing with circuit breaker
  • Durable transaction state — TxIntent state machine with idempotency, replacement, reorg-aware confirmation, restart resume
  • Controller-resolved addresses — sub-contract address discovery from on-chain Controller, no bake-ins
  • Gas oracle — TTL-cached eth_gasPrice + maxPriorityFeePerGas
  • Log subscriptions with durable offsets — restart-safe eth_getLogs poller
  • Reorg-aware confirmation tracking — wait N confirmations before terminal
  • Keystore signing — V3 JSON in v1; HSM/KMS shaped for v2
  • BoltDB persistence — single-writer key-value, embedded
  • Structured logging — stdlib log/slog wrapper
  • Prometheus-recordable metrics — via a Recorder interface (no Prometheus dependency)

chain-commons is a library, never a daemon. It has no cmd/, no main, no Docker image. External workload binaries (transcode, inference, etc.) talk to the chain-aware daemons over local gRPC; they don't import chain-commons directly.

Status

This is the first scaffolding milestone (plan 0001 §D–§K). Currently shipping:

  • ✅ All 11 provider interfaces (rpc, controller, keystore, gasoracle, logs, receipts, timesource, store, metrics, logger, clock)
  • ✅ services/txintent — full durable state machine + persistence + idempotency, comprehensive test suite
  • ✅ services/{roundclock, eventlog} — interfaces only; impls land later
  • ✅ In-memory Store (production BoltDB impl lands later)
  • ✅ slog-backed Logger (production impl)
  • ✅ No-op Recorder (production decorators live in daemons)
  • ✅ System Clock
  • ⏳ Provider implementations for rpc, controller, gasoracle, keystore, logs, receipts, timesource — land in subsequent commits
  • ⏳ services/txintent Processor (signing/broadcasting/receipt-tracking goroutine) — lands in subsequent commit

The interfaces are stable enough to be consumed; consumer daemons can dial against fakes from testing/ (when it lands) and switch to real impls without API churn.

Layout

chain-commons/
├── chain/              typed domain values
├── errors/             classified error types + Classify()
├── config/             validated Config struct
├── providers/          interfaces + per-provider impls
│   ├── rpc/            multi-URL go-ethereum wrapper (impl pending)
│   ├── controller/     sub-contract address resolver (impl pending)
│   ├── keystore/       V3 JSON keystore + HSM-shaped Sign() (impl pending)
│   ├── gasoracle/      eth_gasPrice + maxPriorityFeePerGas TTL cache (impl pending)
│   ├── logs/           eth_getLogs poller with durable offsets (impl pending)
│   ├── receipts/       reorg-aware confirmation tracking (impl pending)
│   ├── timesource/     current round + L1 block + Round events (impl pending)
│   ├── store/          BoltDB-backed KV (memory impl shipped; bolt impl pending)
│   ├── metrics/        Recorder interface + no-op
│   ├── logger/         slog wrapper
│   └── clock/          time.Now + tickers
├── services/
│   ├── txintent/       durable transaction state machine ✅ shipped
│   ├── roundclock/     typed Round events (impl pending)
│   └── eventlog/       durable log subscriptions (impl pending)
├── testing/            fakes for every provider (impl pending)
├── lint/               coverage-gate, layer-check, no-secrets-in-logs
├── go.mod
├── Makefile
└── .golangci.yml

Usage

make build           # go build ./...
make test            # go test ./...
make test-race       # go test -race ./...
make lint            # go vet + golangci-lint (if installed)
make coverage-check  # per-package coverage report

Design

Full design at the monorepo root:

The build-out plan: docs/exec-plans/active/0001-establish-monorepo-and-chain-commons.md.

License

MIT.

Documentation

Overview

Package chaincommons is the shared chain-glue library for the livepeer-modules-project monorepo.

It provides the Ethereum/Arbitrum interaction primitives that payment-daemon, service-registry-daemon, and protocol-daemon all consume: multi-RPC failover, durable transaction state, Controller- resolved sub-contract addresses, gas oracle, log subscriptions with durable offsets, reorg-aware confirmation tracking, keystore signing, BoltDB persistence, structured logging, and Prometheus-recordable metrics (via a Recorder interface — no direct Prometheus dependency).

chain-commons is a library, never a daemon. It has no cmd/, no main, and no Docker image. It is consumed by daemons.

See docs/design-docs/chain-commons-api.md in the monorepo for the full API surface; docs/design-docs/{tx-intent-state-machine, multi-rpc-failover, controller-resolver, event-log-offsets}.md cover individual subsystems.

Source Files

View all Source files

Directories

Path Synopsis
Package chain holds the typed domain values used across chain-commons.
 Package chain holds the typed domain values used across chain-commons.
Package config holds the validated config used to construct chain-commons providers and services.
 Package config holds the validated config used to construct chain-commons providers and services.
Package errors holds the classified error types used across chain-commons.
 Package errors holds the classified error types used across chain-commons.
providers
bondingmanager
Package bondingmanager provides read-only ABI bindings to Livepeer's BondingManager contract — the calls every chain-aware daemon needs:
 Package bondingmanager provides read-only ABI bindings to Livepeer's BondingManager contract — the calls every chain-aware daemon needs:
clock
Package clock provides a testable time abstraction.
 Package clock provides a testable time abstraction.
controller
Package controller provides the on-chain Controller-resolved sub-contract address abstraction.
 Package controller provides the on-chain Controller-resolved sub-contract address abstraction.
controller/eth
Package eth provides a controller.Controller backed by on-chain Controller.getContract(bytes32) calls via providers/rpc.RPC.
 Package eth provides a controller.Controller backed by on-chain Controller.getContract(bytes32) calls via providers/rpc.RPC.
gasoracle
Package gasoracle provides the gas-pricing abstraction.
 Package gasoracle provides the gas-pricing abstraction.
gasoracle/ttl
Package ttl provides a TTL-cached gasoracle.GasOracle that wraps providers/rpc.RPC's SuggestGasPrice + SuggestGasTipCap.
 Package ttl provides a TTL-cached gasoracle.GasOracle that wraps providers/rpc.RPC's SuggestGasPrice + SuggestGasTipCap.
keystore
Package keystore provides the signing abstraction.
 Package keystore provides the signing abstraction.
keystore/v3json
Package v3json provides a V3 JSON keystore implementation of the keystore.Keystore interface.
 Package v3json provides a V3 JSON keystore implementation of the keystore.Keystore interface.
logger
Package logger provides a structured-logging abstraction.
 Package logger provides a structured-logging abstraction.
logs
Package logs provides the eth_getLogs poller with durable per-subscriber offsets.
 Package logs provides the eth_getLogs poller with durable per-subscriber offsets.
logs/poller
Package poller provides a logs.Logs implementation backed by polled eth_getLogs calls with durable per-subscriber offsets persisted via the store.Store provider.
 Package poller provides a logs.Logs implementation backed by polled eth_getLogs calls with durable per-subscriber offsets persisted via the store.Store provider.
metrics
Package metrics provides the Recorder interface used by chain-commons services to emit metrics, plus a no-op default implementation.
 Package metrics provides the Recorder interface used by chain-commons services to emit metrics, plus a no-op default implementation.
receipts
Package receipts provides reorg-aware transaction confirmation tracking.
 Package receipts provides reorg-aware transaction confirmation tracking.
receipts/reorg
Package reorg provides a reorg-aware receipts.Receipts implementation.
 Package reorg provides a reorg-aware receipts.Receipts implementation.
roundsmanager
Package roundsmanager provides read-only ABI bindings to Livepeer's RoundsManager contract — the calls every chain-aware daemon needs:
 Package roundsmanager provides read-only ABI bindings to Livepeer's RoundsManager contract — the calls every chain-aware daemon needs:
rpc
Package rpc provides the multi-URL Ethereum RPC abstraction with circuit-breaker failover.
 Package rpc provides the multi-URL Ethereum RPC abstraction with circuit-breaker failover.
rpc/multi
Package multi provides a multi-URL Ethereum RPC implementation with per-endpoint circuit breakers and primary/backup failover.
 Package multi provides a multi-URL Ethereum RPC implementation with per-endpoint circuit breakers and primary/backup failover.
store
Package store provides a BoltDB-backed key-value store, plus a Bucket abstraction that services use for their own persistent state.
 Package store provides a BoltDB-backed key-value store, plus a Bucket abstraction that services use for their own persistent state.
store/bolt
Package bolt provides a BoltDB-backed implementation of providers/store.Store.
 Package bolt provides a BoltDB-backed implementation of providers/store.Store.
timesource
Package timesource provides on-chain time abstraction: current round, current L1 block, and typed Round event subscriptions.
 Package timesource provides on-chain time abstraction: current round, current L1 block, and typed Round event subscriptions.
timesource/poller
Package poller provides a polling-based timesource.TimeSource that wraps providers/rpc.RPC.
 Package poller provides a polling-based timesource.TimeSource that wraps providers/rpc.RPC.
services
eventlog
Package eventlog wraps providers/logs with stronger lifecycle semantics for service-level consumers.
 Package eventlog wraps providers/logs with stronger lifecycle semantics for service-level consumers.
roundclock
Package roundclock emits typed Round events on top of the timesource and logs providers, with last-emitted round persisted to the store so a daemon restart does not re-fire stale Round events.
 Package roundclock emits typed Round events on top of the timesource and logs providers, with last-emitted round persisted to the store so a daemon restart does not re-fire stale Round events.
txintent
Package txintent provides the durable transaction state machine that every on-chain write across the monorepo uses.
 Package txintent provides the durable transaction state machine that every on-chain write across the monorepo uses.
Package testing provides fakes for every chain-commons provider so that downstream daemon test suites don't dial real RPC, write to real BoltDB files, or import sensitive keystore content.
 Package testing provides fakes for every chain-commons provider so that downstream daemon test suites don't dial real RPC, write to real BoltDB files, or import sensitive keystore content.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.