circ

circ is a TypeScript toolkit for issuing and managing Bitcoin-native stablecoin-style assets in the spirit of modern RGB and Taproot Assets stacks: Taproot-friendly issuance metaphors, client-side validation as a design lens (privacy + anchoring to Bitcoin), and a gRPC façade so GUI wallets or POS systems can integrate without adopting Python.

The original brainstorm referenced a Python library; this repository is TypeScript so backend teams get strict typing, fast iteration, and npm install-style ergonomics while still pairing naturally with containerised Bitcoin infra.

Ecosystem context (why “Bitcoin-native stables” exploded in 2025–2026)

Public reporting and builder activity cluster around three themes circ is meant to track:

• RGB + Lightning settlement rails: Infrastructure efforts such as UTEXO Protocol (product docs) describe RGB-anchored stable settlement executed over Lightning-style payment flows—see also mainstream coverage of Utexo’s funding/advisory momentum around RGB-native USDT settlement (AP News press release). RGB’s own Lightning compatibility overview summarises how RGB assets can ride channel semantics.
• Taproot Assets on Lightning: Lightning Labs’ Taproot Assets builder docs describe how dollar/stable instruments can ride Lightning channels with Taproot-native proofs—recent posts highlight usability upgrades like reusable addresses and supply attestations aimed at production stablecoin workflows (Taproot Assets v0.7 announcement). Earlier milestones expanded Lightning-facing stablecoin UX (Taproot Assets v0.6 announcement, USDT on Bitcoin/Lightning via Taproot Assets).
• Product narratives beyond RGB: Teams continue experimenting with BTC-collateralised or rollup-issued dollar instruments on Bitcoin-aligned stacks (often discussed under labels like CirBTC/Citrea ctUSD style designs). circ stays protocol-agnostic: it gives you inventory + invoice semantics + RPC wiring, not legal claims about any issuer.

circ itself ships a simulator ledger plus optional Docker wiring toward real dependency graphs you see in rgb-lightning-sample style setups. For a compact, third‑party comparison of how client-side proofs differ across stacks, see RGB vs Taproot Assets (Atlas21 overview—not endorsement).

What ships in this repo

Layer	What you get
Domain core	Strongly typed issuance metadata, balances, transfers, invoices, settlement helpers
Anchors	Synthetic commitments / hints for demos—not RGB consensus bytes
gRPC	proto/circ.proto (Health, IssueAsset, GetBalance, SendPayment, CreateInvoice, PayInvoice)
Docker Compose	Bitcoin Core regtest, optional RGB proxy, shared circ_net — attach rgb-lightning-node for a combined RGB + Lightning daemon

Requirements

• Node.js 20+

Quick start

cd circ    # repository root
npm install
npm run build
npm test
npm start                # CIRC_GRPC_HOST / CIRC_GRPC_PORT (defaults 0.0.0.0:50051)

Variable	Default	Purpose
CIRC_GRPC_HOST	0.0.0.0	Bind address
CIRC_GRPC_PORT	50051	Listen port

Library usage

import {
  InMemoryStablecoinLedger,
  startCircGrpcServer,
  createCircGrpcClient,
} from "./dist/index.js"; // or from "circ" when published / npm-linked

const ledger = new InMemoryStablecoinLedger();
const asset = ledger.issueAsset({
  ticker: "USDt",
  name: "Demo RGB-flavoured dollar unit",
  supplyAtoms: 1_000_000n,
  decimals: 6,
  issuerWalletId: "issuer",
});

ledger.transfer({
  fromWalletId: "issuer",
  toWalletId: "merchant",
  assetId: asset.assetId,
  amountAtoms: 50_000n,
});

const running = await startCircGrpcServer(ledger, "127.0.0.1", 50051);
// await running.shutdown();

Docker Compose (bitcoind ± RGB proxy)

Bitcoin Core only (fast feedback):

docker compose up -d bitcoind

RPC listens on localhost:18443 with user/pass circ / circ.

Add RGB proxy sidecar (mirrors many upstream samples; helpful when exercising invoice transport):

docker compose --profile rgb up -d

That publishes proxy traffic on localhost:3000. The referenced ghcr.io/grunch/rgb-proxy-server image appears in historical RGB samples; newer maintenance may live under RGB-Tools/rgb-proxy-server—swap the image pin when you standardise on the maintained fork.

Bitcoin Core also exposes ZMQ (28332/28333) for indexers.

Where Lightning + RGB enter

RGB-capable Lightning today typically means rgb-lightning-node (combined LN + RGB custody surface) plus Electrum/Esplora-style indexers depending on your topology. circ does not vendor those binaries (they evolve quickly), but Compose attaches everything to circ_net so you can:

1. docker compose up -d bitcoind (and --profile rgb if you want the proxy).
2. Build/run rgb-lightning-node per upstream docs with --network circ_net so containers resolve bitcoind.
3. Gradually replace InMemoryStablecoinLedger with adapters calling that daemon’s HTTP/OpenAPI surface.

For a batteries-included reference stack (mining scripts, electrs, etc.), clone RGB-Tools/rgb-lightning-sample alongside circ rather than duplicating their Compose graph here.

gRPC surface

Regenerate clients with protoc + your favourite plugins; the schema ships at proto/circ.proto (copied next to dist/proto after npm run build).

RPC	Role
Health	Liveness/version
IssueAsset	Allocate logical supply to an issuer wallet handle
GetBalance	Read simulated balances
SendPayment	Move atoms between wallet handles
CreateInvoice	Merchant invoice + opaque payload string
PayInvoice	Customer settles invoice (invoice is consumed; paying twice returns NOT_FOUND)

Security & scope

• Not audited custody software.
• Simulator hashes are pedagogical, not Taproot Asset proofs or RGB contract witnesses.
• Stay on regtest/signet until your compliance + ops teams bless mainnet flows.

Development

npm run dev
npm run test:watch
npm run clean && npm run build
npm run lint          # tsc --noEmit

Release housekeeping: bump package.json "version" only — CIRC_VERSION is loaded from it at runtime.

License

MIT

Contact Info

Telegram: @AuraTerminal