Getting Started

Getting Started with FractaLedger

This guide will help you set up and start using FractaLedger in your project.

Table of Contents

Prerequisites

Before installing FractaLedger, ensure you have the following prerequisites:

Node.js (v14 or later)

Required to run the application. You can download it from nodejs.org.

# Check your Node.js version
node --version

npm (v6 or later)

Required to install dependencies. This comes bundled with Node.js.

# Check your npm version
npm --version

Git

Required for version control and cloning the repository. You can download Git from git-scm.com.

# Check your Git version
git --version

Installation

Installing as a Dependency in Your Project

You can install FractaLedger as a dependency in your existing Node.js project:

1

Install FractaLedger

npm install fractaledger
2

Initialize a New FractaLedger Project

npx fractaledger-init --dir my-fractaledger-project

This command creates a new FractaLedger project with the necessary directory structure and configuration files.

3

Navigate to Your Project Directory

cd my-fractaledger-project
4

Edit Configuration Files

Update fractaledger.json with your blockchain connection details and add your wallet secrets to .env (keep this file secure and never commit it to version control).

5

Start the System

npm start

Installing from Source

You can also install FractaLedger directly from the source code:

1

Clone the Repository

git clone https://github.com/aryanduntley/fractaledger.git
cd fractaledger
2

Install Dependencies

npm install
3

Copy Configuration Templates

cp fractaledger-template.json fractaledger.json
cp .env.example .env
4

Edit Configuration Files

Update fractaledger.json with your blockchain connection details and add your wallet secrets to .env (keep this file secure and never commit it to version control).

5

Start the System

npm start

Configuration

FractaLedger uses a configuration-based approach that allows you to specify how to connect to various blockchains and how to manage your wallets.

Configuration Files

There are two main configuration files:

  • fractaledger.json - Main configuration file for blockchain connections, wallet management, and system settings
  • .env - Environment variables file for sensitive information like private keys and API keys

Example Configuration

Here's a simplified example of a fractaledger.json file:

{
  "bitcoin": [
    {
      "name": "btc_wallet_1",
      "network": "mainnet",
      "walletAddress": "bc1q...",
      "secretEnvVar": "BTC_WALLET_1_SECRET",
      "transceiver": {
        "method": "callback",
        "module": "./transceivers/utxo-transceiver.js",
        "config": {
          "apiUrl": "https://blockstream.info/api",
          "monitoringInterval": 60000
        }
      }
    }
  ],
  "api": {
    "port": 3000,
    "host": "localhost"
  }
}

And here's an example of a .env file:

# Bitcoin wallet secrets
BTC_WALLET_1_SECRET=your-private-key-or-seed-phrase

# API configuration
JWT_SECRET=your-jwt-secret
API_PORT=3000
Important: Never commit your .env file to version control. It contains sensitive information that should be kept secure.

Configuration Setup

FractaLedger requires proper configuration to connect to blockchain networks and manage wallets. This section will guide you through setting up the necessary configuration files.

Setting Up Configuration Files

1

Create Configuration Files

After installing FractaLedger, you need to create configuration files based on the provided templates:

# Copy the configuration template
cp fractaledger-template.json fractaledger.json

# Copy the environment variables template
cp .env.example .env
2

Edit Configuration Files

Edit the fractaledger.json file to configure your blockchain connections and wallet settings:

{
  "bitcoin": [
    {
      "name": "btc_wallet_1",
      "network": "mainnet",
      "walletAddress": "YOUR_WALLET_ADDRESS",
      "secretEnvVar": "BTC_WALLET_1_SECRET",
      "transceiver": {
        "method": "callback",
        "module": "./transceivers/utxo-transceiver.js",
        "config": {
          "apiUrl": "https://blockstream.info/api",
          "monitoringInterval": 60000
        }
      }
    }
  ],
  "api": {
    "port": 3000,
    "host": "localhost"
  }
}
3

Set Environment Variables

Edit the .env file to set your wallet secrets and other sensitive information:

# Wallet secrets
BTC_WALLET_1_SECRET=your_wallet_private_key_or_seed

# API configuration
JWT_SECRET=your_jwt_secret
API_PORT=3000

Important: Never commit your .env file to version control. It contains sensitive information that should be kept secure.

4

Verify Configuration

You can verify your configuration by running the following command:

npx fractaledger-verify-config

This command checks your configuration files for errors and provides suggestions for improvement.

First Steps

Now that you have FractaLedger installed and configured, let's go through some basic operations to get you started.

Creating a Transceiver

FractaLedger uses transceivers to interact with blockchains. You can generate a custom transceiver for your blockchain:

npx fractaledger-generate-transceiver --type bitcoin --output ./my-transceivers

This command generates a custom transceiver implementation for Bitcoin in the ./my-transceivers directory.

Creating an Internal Wallet

You can create an internal wallet using the API:

curl -X POST http://localhost:3000/api/internal-wallets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "id": "internal_wallet_1",
    "blockchain": "bitcoin",
    "primaryWalletName": "btc_wallet_1",
    "description": "Customer wallet for user123",
    "metadata": {
      "userId": "user123",
      "customerType": "premium"
    }
  }'

Making an Internal Transfer

You can transfer funds between internal wallets:

curl -X POST http://localhost:3000/api/transactions/internal-transfer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "fromInternalWalletId": "internal_wallet_1",
    "toInternalWalletId": "internal_wallet_2",
    "amount": 0.1,
    "memo": "Payment for services"
  }'

Withdrawing Funds

You can withdraw funds from an internal wallet to an external address:

curl -X POST http://localhost:3000/api/internal-wallets/internal_wallet_1/withdraw \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "toAddress": "bc1q...",
    "amount": 0.1,
    "fee": 0.0001
  }'

Troubleshooting

Here are some common issues you might encounter and how to resolve them:

Configuration Issues

Symptom: Error messages like "Invalid configuration" or "Missing required configuration".

Solution:

  • Check your fractaledger.json file for syntax errors.
  • Ensure all required fields are present in your configuration.
  • Verify that your .env file contains all the required environment variables.

Transceiver Issues

Symptom: Error messages like "Failed to broadcast transaction" or "Failed to monitor wallet address".

Solution:

  • Check your transceiver configuration in fractaledger.json.
  • Ensure the API URL is correct and accessible.
  • Verify that your wallet address and private key are correct.
  • Check the blockchain network status (mainnet/testnet).

API Authentication Issues

Symptom: 401 Unauthorized errors when accessing API endpoints.

Solution:

  • Ensure you're including the JWT token in the Authorization header.
  • Check that the JWT token is valid and not expired.
  • Verify that the JWT secret in .env matches the one used to generate the token.

Balance Reconciliation Issues

Symptom: Error messages like "Balance discrepancy detected" or "Failed to reconcile wallet balances".

Solution:

  • Check the on-chain balance of your primary wallet.
  • Verify that the sum of internal wallet balances doesn't exceed the primary wallet balance.
  • Check for pending transactions that might affect the balance.
  • Adjust the warningThreshold in the reconciliation configuration if needed.

Next Steps

Now that you have FractaLedger up and running, you can explore more advanced features:

Transceivers

Learn how to implement custom transaction broadcasting and monitoring.

Chaincode

Customize smart contracts for your specific use case.

Advanced Features

Explore internal transfers, base wallet protection, and more.