Skip to content

README.md

Latest commit

 

History

History
249 lines (199 loc) · 12.4 KB

README.md

File metadata and controls

249 lines (199 loc) · 12.4 KB

@fabric/core — the Fabric Reference Client

Project Status Coverage Status GitHub contributors

Status: 0.1.0-RC1 — run npm run ci before release tags (full test suite).

Doc Purpose
VISION.md Product vision, architecture snapshot, documentation map
DEVELOPERS.md Repo layout, tests, core types, storage
docs/PRODUCTION.md Node version, native deps, downstream alignment
PRIVACY.md Privacy model for operators
CHANGELOG.md Release notes
docs/README.md Index of operational and generated docs

The @fabric/core project provides an API for building peer-to-peer applications on Bitcoin.

Fabric is an experimental approach to the secure establishment and execution of peer-to-peer agreements ("contracts") using Bitcoin as a bonding mechanism. The @fabric/core project provides a robust set of implementations as JavaScript classes, enabling the rapid prototyping and testing of Bitcoin-based applications for downstream developers.

Quick Start

npm i -g FabricLabs/fabric#master

You'll now have the fabric binary available on your system. Set up your environment with a newly-generated cryptographic key by using:

fabric setup
🚨 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.

Once complete, you'll have a fully configured Fabric client available by running:

fabric

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-CHECKLIST.md (tests, lint gates, audit reports, optional make:dev + check:book-links). 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 creates a local Fabric node.

Native Dependencies

Installing from npm may compile native addons (node-gyp). Typical toolchain needs: Node 22.x, Python 3 (for node-gyp), plus secp256k1, libwally-core, and noise libraries for fabric.node — see BUILD.md.

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

API

The Fabric reference implementation exposes a simple message-passing interface using the actor model, enabling your downstream applications to subscribe to simple events for rapid prototyping of distributed applications.

Using as a Library

Using the EventEmitter pattern, you can create an instance of Fabric to use it as an event source.

Simple Example

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) Coverage Status
@fabric/hub run your own Fabric Hub Coverage Status
@fabric/doorman an artificially intelligent assistant Coverage Status

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