@fabric/core — the Fabric Reference Client

The @fabric/core project is the 0.1 RC reference client for building peer-to-peer applications on Bitcoin: NOISE Peer messaging with bounded gossip/discovery, Bitcoin-settled document-exchange helpers, and local Program / Machine execution.

Fabric remains experimental. This release is not a sandboxed remote contract VM or a production-hardened dapp SDK — see PUBLIC_API.md for the frozen leaf import map and scoped claim.

Bitcoin

We've designed Fabric to extend the existing Bitcoin ecosystem, deriving all specifications from well-established designs and implementations.

Identity

BIP32 Extensions

mainnet Master: m'/
mainnet Identity #0: m'/7777/
mainnet Identity #0: m'/7777/
mainnet Identity #0, Receive 0: m'/7777/
mainnet Identity #0, Change 0: m'/7777/
mainnet Identity #0, Receive 1: m'/7777/
regtest Master:
regtest Identity #0:

Status: 0.1.0-RC1 (experimental reference) — run npm run ci before release tags.

Doc	Purpose
PUBLIC_API.md	Frozen 0.1 leaf imports + release claim
VISION.md	Product vision, architecture snapshot, documentation map
DEVELOPERS.md	Repo layout, tests, core types, storage
PROTOCOL.md	Wire entry → docs/MESSAGE_BODY.md
docs/BOLT_COMPATIBILITY.md	Lightning BOLT #1–#12 vs lightningd / Lightning
docs/FABRIC_LIGHTNING_OFFERS.md	Fabric markets vs BOLT12; Lightning.Bolt12
docs/FABRIC_PAYMENT_BECH32.md	Fabric-routed payments fa1…; Lightning.FabricPayment
docs/LIGHTNING_COMPAT.md	Core Lightning JSON-RPC ↔ Fabric API
PRIVACY.md	Privacy model for operators
SECURITY.md / AUDIT.md	Hardening notes + known gaps
CHANGELOG.md	Release notes

Quick Start

npm i -g @fabric/core
fabric setup
fabric

🚨 Stop here!
The output of fabric setup includes your SEED. Never share it or store it in plain text in cloud-synced folders. Write it down offline or use a password manager.

For help, try entering "insert mode" by pressing the "i" key then typing /help and pressing enter — you'll get a short help prompt followed by a list of available commands. Feel free to explore!

If you run into any trouble, read on for clues, then join the chat with any remaining questions.

You'll also want bitcoind installed, and fully synchronized with your preferred network. You can use scripts/playnet.sh to run a local playnet node, for which you can use the faucet: https://faucet.playnet.fabric.pub

What is Fabric?

@fabric/core provides the reference implementation for the Fabric Protocol, a "language" for exchanging information through peer-to-peer networks. Written in JavaScript, it is meant to be well-documented and easy to understand — but not the final implementation.

Contributing

Fork and clone the Fabric GitHub repository and launch a local web server with npm run examples to view the examples, or npm run docs once you're ready to integrate Fabric into your application.

Compiling from Source

See also BUILD.md for a full guide, including Bitcoin and Lightning.

See BUILD.md for the native addon (npm run build:c), system libraries (libwally-core, secp256k1, noise), and JS-only workflows. C↔JS message wire parity is documented in docs/C-JS-PARITY.md. Ongoing JavaScript work is outlined in docs/JS-PLAN.md.

git clone git@github.com:FabricLabs/fabric.git
cd fabric
git checkout feature/v0.1.0-RC1
npm ci
npm test
# optional: compile N-API addon
npm run build:c

For global CLI install: npm install -g (after npm ci / npm install in the repo).

Production

Before tagging or publishing, use docs/PRODUCTION.md (pre-flight + release checklist). CI on push/PR runs smoke, lint, tests with coverage (after bitcoind is available), then installs Lightning for downstream tooling.

Available Commands

• The fabric binary is the Node harness for the default Blessed TUI (chat); optional fabric.node accelerates a tiny crypto surface — see docs/CLI-BINARY.md.
• npm run cli runs scripts/fabric.js (same entry as npm run chat).
• npm run dev serves a developer interface over localhost HTTP.
• npm run docs creates a local HTTP server for browsing documentation.
• npm run examples creates a local HTTP server for interacting with examples.
• npm start launches the Fabric shell locally (same as npm run chat).

Native Dependencies

npm install does not build the C addon — JavaScript is the canonical protocol for 0.1.0. Optional fabric.node: npm run build:c or FABRIC_BUILD_NATIVE=1 (see BUILD.md). Typical toolchain for an optional native build: Node 24.15.x, Python 3, secp256k1, libwally-core, and noise.

JS tests do not require fabric.node. Separately, level and zeromq may compile platform bindings when those packages are installed.

API

Prefer leaf imports from PUBLIC_API.md (Peer, Message, Key, document helpers). The Fabric facade is for demos; production apps should not depend on Fabric.* statics.

Using as a Library

const Peer = require('@fabric/core/types/peer');

async function main () {
  const peer = new Peer({
    alias: 'Example',
    peers: ['hub.fabric.pub:7777']
  });

  peer.on('message', (message) => {
    console.log('Received message from Fabric:', message);
  });

  peer.start();
  return { peer };
}

main().catch((exception) => {
  console.error('Example error:', exception);
}).then((output) => {
  console.log('Example output:', output);
});

Plugins

Fabric is an extensible framework, supporting a variety of plugins.

Package	Description	Status
@fabric/http	serve Fabric apps to the legacy web (HTTP)
@fabric/hub	run your own Fabric Hub
@fabric/doorman	an artificially intelligent assistant

Running on Fabric

Several successful projects are built with or are running on Fabric, including:

• Doorman, an artificially intelligent assistant
• IdleRPG, a simple RPG game which rewards you for remaining idle
• Verse, a virtual universe simulator

To add your project to the list, read the API docs, create a public repository for the source code, then edit this file to include a link to your work.

Edge Nodes

Full Fabric nodes connected to the World Wide Web (WWW). Only SSL (port 443) is supported.

Host	Status
hub.fabric.pub	ONLINE
labs.fabric.pub	OFFLINE

Fabric Projects

Either Fabric libraries or projects running Fabric, this list encompasses the most interesting work in the ecosystem.

Name	Description	Status	v0.1.0-RC1 ready
@fabric/core	Core library	Active	In RC
@fabric/http	HTTP bridge	Active	In RC
hub.fabric.pub	Public hub	See Edge Nodes	—
labs.fabric.pub	Labs hub	OFFLINE	—
sensemaker.io	—	—	No
verse.pub	—	—	—

Learning More

The best place to get started is in the #learning channel, a collection of impassioned educators eager to help you.

Fabric on Twitter: @FabricProtocol