Essential javascript architecture for the Fuel side chain

Usage no npm install needed!

<script type="module">
  import fuelCore from 'https://cdn.skypack.dev/fuel-core';


Fuel Core

npm version

Gitter chat

Essential JavaScript architecture for the Fuel side chain.


  • A complete optimistic rollup side-chain implementation in JS
  • Extremely cheap (under 3840 wei per transaction)
  • Pre-cleared instant transactions (1.4 to .8 seconds on average)
  • Multi-network testnet support in Goerli and Ropsten
  • Meta-transactional by default (pay fees in any ERC20)
  • Complete node, faucet and wallet implementations
  • Live pubsub support for instant balance updates
  • Works with any ERC20 token (simply deposit to use)
  • Supports HTLC's for instant atomic swaps
  • High throughput capability (surge approx. 10k tps, on-chain 250tps)
  • Censorship resistant (enter and exit at will)
  • Completely open-source under Apache-2.0


npm install --save fuel-core


import { Wallet, utils } from "fuel-core";

const { faucet, transfer, listen, tokens, balance, address } = new Wallet({
   signer: new utils.SigningKey(utils.randomBytes(32)),

(async () => {
  await listen(async () => {
    console.log(await balance(tokens.fakeDai));

  await faucet();

  await transfer(500, tokens.fakeDai, address);

Deposit / Withdraw

import { Wallet, utils, providers, dbs } from "fuel-core";

const { deposit, balance, withdraw, retrieve, tokens } = new Wallet({
  signer: utils.SigningKey(utils.randomBytes(32)),
  provider: new providers.Web3Provider(window.web3.currentProvider),
  db: new dbs.Index(),
  chainId: 3, // default is 3 Ropsten (only supported)

(async ()=>{

  await deposit(1000, tokens.ether /*, { from: eth_accounts[0] } */);

  console.log(await balance(tokens.ether));

  await withdraw(500, tokens.ether); // make a withdrawal UTXO

  await retrieve(tokens.ether); // wait 1 weeks, select withdrawal zero or first withdrawal in DB to retrieve [, withdrawlIndex]


Listener Support

const { listen } = new Wallet(...);

(async ()=>{

  // a cb can be added here, results are { key: , value: } objects.
  // fires for all wallet events and incoming transactions
  await listen(/* callback */);



const { sync } = new Wallet(...);

// Sync your wallet DB with the Fuel API
(async ()=>{

  await sync();



new Wallet({
  signer, // [Object] ethers Signer object
  provider, // [Object] web3 provider object
  db: new dbs.Memory(), // [Object] database object
  chainId: '3' // [String | Number] '3' Ropsten or '5' Goerli (only supported)
  // alternative: [String] network: 'ropsten' // or 'goerli'


const { dbs } = require('fuel-core');

new dbs.Index(...); // Based on window.localStorage
new dbs.Level({ ... }); // Level store (level)
new dbs.Memory({ ... }); // Memory storage (memdown)

Running a Node

git clone https://github.com/fuellabs/fuel-core
# setup your environment variables (described below)
npm install
# then run one of the following commands
  • Full Sync - npm run node-sync-ropsten runs a full node with mempool optionality with remote MySQL DB
  • Faucet - npm run node-faucet-ropsten runs a faucet node (for fund requests/dispersal of test tokens)
  • Verifier npm run node-verifier-ropsten runs a verifier node (no mempool or block production)
  • Gancache npm run node-ganache runs a local Ganache server

Note, Goerli is also supported, i.e. npm run node-sync-goerli etc.

Building and Deploying

  • Build Fuel npm run build-fuel builds the Fuel.sol contracts, writes artifacts
  • Deploy Fuel npm run deploy-fuel-ropsten deploys Fuel based on environmental configuration (npm run deploy-fuel-goerli also supported)

Running a Test MySQL Sync Node

  1. Fill out environment variables.
  2. One instance:
npm run node-ganache
  1. Another instance:
npm run test-node-sync

Environment Variables

Set these in your ~/.bashrc or ~/.bash_profile to operate the sync and dispersal nodes.

# Web3 HTTP Provider (string - url.. Infura or Other *Required*)
# goerli_web3_provider="https://.."

# MySQL Database Environment (string[s] - mysql connection settings, optional for sync or verifier nodes)
# ropsten_mysql_host
# ropsten_mysql_port
# ropsten_mysql_database
# ropsten_mysql_user
# ropsten_mysql_password

# goerli_mysql_host
# goerli_mysql_port
# goerli_mysql_database
# goerli_mysql_user
# goerli_mysql_password

# Keys (string - 64 byte hex)
# block_production_key=0x..
# fraud_commitment_key=0x..
# transactions_submission_keys=0x..[, 0x...]

# Faucet (string - hex)
# faucet_key=0x..

# Faucet (numberish - hex | number)
# faucet_token_id=1
# faucet_dispersal_amount=0x..

# Sentry Error Reporting (optional)
# sentry=https://..

# Monitor Memory (boolish, optional)
# memwatch=1

# Verifier Only (no block production, only fraud commitments etc..) (boolish, optional)
# verifier=1

# Chain Identifier (number, eventually 1 Mainnet or 3 Ropsten are supported, default: 3)
# chain_id=3

# Gas Limit (string - hex)
# gasLimit=0x..

# PubNub
# pubnub_publisher_key=
# pubnub_subscriber_key=

Help out

There is always a lot of work to do, and will have many rules to maintain. So please help out in any way that you can:

  • Create, enhance, and debug fuel-core rules (see our guide to "Working on rules").
  • Improve documentation.
  • Chime in on any open issue or pull request.
  • Open new issues about your ideas for making fuel-core better, and pull requests to show us how your idea works.
  • Add new tests to absolutely anything.
  • Create or contribute to ecosystem tools.
  • Spread the word!

We communicate via issues and pull requests.

Important documents


Please consider donating if you think Fuel is helpful to you or that my work is valuable. I am happy if you can help us buy a cup of coffee. ❤️

Or just send us some Dai, USDC or Ether:

0x3e947a271a37Ae7B59921c57be0a3246Ee0d887C Etherscan


This project is licensed under the Apache-2.0 license, Copyright (c) 2020 Fuel labs. For more information see LICENSE

Copyright 2020 Fuel Labs

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.