fractaledger
Advanced tools
A configurable off-chain UTXO management system that enables fractional ownership, secure fund distribution, and seamless on-chain interactions across multiple blockchains.
Status: Initial Release š§
This is the first release of FractaLedger. While the core functionality is in place, some instability is possible, and breaking changes may occur in future releases.
Please try it out, and report any bugs or feedback to help us improve it.
FractaLedger is a configurable off-chain UTXO management system that enables fractional ownership, secure fund distribution, and seamless on-chain interactions across multiple blockchains.
FractaLedger solves the challenge of managing fractional ownership of UTXO-based cryptocurrencies (Bitcoin, Litecoin, Dogecoin, etc.) without requiring expensive on-chain transactions for every operation. It uses Hyperledger Fabric as an internal ledger to track fractional ownership while maintaining the security and transparency of blockchain technology.
Less techy description:
If you want to collect fees from UTXO transfers when facilitating point-to-point transfers, use Fractalegder. If you want to pay your employees with bitcoin, litecoin, or other UTXO-based coins.. Fractalegder. If you want to set up a bitcoin community and have intra-community transfers without the high bitcoin fees or long completion times (yes, Fractalegder). Fractaledger is a modularized system that allows you to plug it into a project of your own and interact with it via an API.
You supply a primary on-chain wallet (and secret for transaction signing) and the node infrastructure. You can then connect the Fractalegder transceiver to your on-chain system (full node, SPV, API, whatever). This allows interaction between the primary on-chain wallet(s) and the blockchain. For each primary on-chain wallet, you can create a network of internal wallets (made with hyperledger fabric, smart contract capable). Internal wallets can be assigned to all community members (employees, receivers of funds, whatever you can think of). You have to create the ecosystem around that (front end internal wallets for the users, backend interaction with Fractalegder, etc.) based on your own unique implementations, ideas or business.
The internal wallets can interact with each other, transferring funds between each other. And when a user wishes to withdraw funds from the internal wallet to their own on-chain wallet, they initiate the request. The request passes through the primary on-chain wallet and funds are sent from that primary on-chain wallet to the receiving address. If funds are sent from an external source directed to an internal wallet, that logic is on you to implement. You would track your primary on-chain wallet for the specific transaction and map to the destination (the internal wallet) yourself. Then use the API or direct code (could be handled with the smart contract alone) of Fractalegder to "fund" that internal wallet.
NOTE: The actual on-chain funds go to the primary on-chain wallet. The funding of the internal wallets are representative of that wallet's claim to some given amount relative to the primary on-chain wallet. The amount those internal wallets have or receive is managed by you (employee payroll, primary wallet as simply a passthrough to community internal wallets, etc.).
Fractaledger has a robust tracking system to ensure that the primary on-chain wallet does not have fewer funds than the aggregate sum of the internal wallets. However, Fractalegder does not control the primary on-chain wallet. You do. So, if you remove excessive funds from that primary on-chain wallet, you will get errors and warnings. You are responsible for reconciling the disparity.
Fractaledger creates a special base internal wallet with each primary on-chain wallet that tracks the excess funds in the primary on-chain wallet. If you have 1 BTC in the primary on-chain wallet. And two internal wallets each with .25 BTC. Those two internal wallets have an aggregate sum of .5 BTC. The base internal wallet will show a balance of .5 BTC as well (the difference between the total sum of the internal wallets and the primary on-chain wallet). This base wallet helps prevent users from overdrawing from the primary on-chain wallet. So for admins, you can allow access to that base internal wallet to make withdraws against it instead of the primary on-chain wallet itself. This reduces the risk of taking too much money out of the primary on-chain wallet because the base internal wallet is withdraw-only (you cannot transfer to other internal wallets from this base internal wallet) and is limited to the excess funds. You cannot withdraw from it more than the excess. This leaves the amount available, always at least equal, to the sum of the internal wallets.
Export and modify the transceiver (Fractalegder to blockchain node interaction). Export and modify the smart contract(s) for the internal wallets; it can behave in any way you can think to use it. Eport and modify the API; make your own endpoints to handle logic that Fractalegder doesn't natively handle. Make it your own.
Avoid excessive on-chain transfer fees, congestion and wait times. Make bitcoin smart contract capable within your own ecosystem then return to on-chain whenever you want to move funds outside of your ecosystem. Combine Fractaleger with lightning network to reduce costs even more. This is a way to sidestep the limitations of bitcoin and other UTXO blockchains.
Before installing FractaLedger, ensure you have the following prerequisites:
Depending on your transceiver configuration, you may also need:
Hyperledger Fabric - Required for the internal ledger functionality
Transaction Broadcasting Method - Choose one or more:
# Install FractaLedger as a dependency
npm install fractaledger
# Initialize a new FractaLedger project
npx fractaledger-init --dir my-fractaledger-project
# Navigate to your project directory
cd my-fractaledger-project
# Edit configuration files
# - Update fractaledger.json with your blockchain connection details
# - Add your wallet secrets to .env (keep this file secure and never commit it to version control)
# Start the system
npm start
# Clone the repository
git clone https://github.com/yourusername/fractaledger.git
cd fractaledger
# Install dependencies
npm install
# Copy configuration templates
cp fractaledger-template.json fractaledger.json
cp .env.example .env
# Edit configuration files
# - Update fractaledger.json with your blockchain connection details
# - Add your wallet secrets to .env (keep this file secure and never commit it to version control)
# Start the system
npm start
FractaLedger provides several command-line tools to help you get started:
Initialize a New Project
npx fractaledger-init --dir my-fractaledger-project
This command creates a new FractaLedger project with the necessary directory structure and configuration files.
Generate a Transceiver
npx fractaledger-generate-transceiver --type bitcoin --output ./my-transceivers
This command generates a custom transceiver implementation for the specified blockchain.
Generate a Configuration File
npx fractaledger-generate-config --output ./fractaledger.json
This command generates a configuration file with interactive prompts for customization.
FractaLedger requires Hyperledger Fabric as its internal ledger. While the application handles much of the Fabric interaction, you'll need to set up the Fabric network first:
Install Fabric Prerequisites:
Set Up Fabric Network:
Configure FractaLedger:
hyperledger section in config.json with your network details.envFor detailed Hyperledger Fabric setup instructions, including installation requirements, data storage locations, and backup strategies, refer to our Hyperledger Fabric Setup Guide.
For step-by-step installation instructions for all required components, refer to our Installation Guide.
For comprehensive backup procedures and best practices, refer to our Backup Guide.
For general Fabric documentation, refer to the Hyperledger Fabric documentation.
FractaLedger uses a configuration-based approach that allows you to specify how to connect to various blockchains and how to manage your wallets. The main configuration file is config.json, and sensitive information like private keys is stored in environment variables.
See config-template.json for a complete example configuration. Here's a simplified version:
{
"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
}
}
}
],
"hyperledger": {
"networkConfig": {
"channelName": "fractaledger-channel",
"chaincodeName": "fractaledger-chaincode"
}
}
}
FractaLedger uses a flexible transceiver architecture that handles both transaction broadcasting and wallet address monitoring. This approach completely separates transaction creation/signing from the broadcasting and monitoring mechanisms, allowing you to use your existing infrastructure for blockchain interactions.
FractaLedger supports four transceiver methods:
Callback Method
{
"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
}
}
}
Event Method
{
"name": "btc_wallet_2",
"network": "mainnet",
"walletAddress": "bc1q...",
"secretEnvVar": "BTC_WALLET_2_SECRET",
"transceiver": {
"method": "event"
}
}
API Method
{
"name": "btc_wallet_3",
"network": "mainnet",
"walletAddress": "bc1q...",
"secretEnvVar": "BTC_WALLET_3_SECRET",
"transceiver": {
"method": "api"
}
}
Return Method
{
"name": "btc_wallet_4",
"network": "mainnet",
"walletAddress": "bc1q...",
"secretEnvVar": "BTC_WALLET_4_SECRET",
"transceiver": {
"method": "return"
}
}
You can create custom transceiver modules to implement your own transaction broadcasting and wallet address monitoring logic. These modules should implement the UTXOTransceiver interface, which includes methods for:
For more information about custom transceivers, see the transceivers/README.md file.
Sensitive information like private keys and API keys should be stored in environment variables. See .env.example for a complete list of required environment variables.
By default, FractaLedger looks for the .env file in the current working directory. However, you can specify a custom location for your environment file in the config.json:
{
"environment": {
"envFilePath": "/path/to/your/.env"
}
}
This allows you to:
fractaledger/
āāā src/ # Source code
ā āāā api/ # API server
ā āāā blockchain/ # Blockchain connectors
ā ā āāā blockchainConnector.js # Blockchain connector interface
ā ā āāā connectorManager.js # Connector initialization
ā ā āāā transactionBuilder.js # Transaction creation and signing
ā ā āāā transceiverManager.js # Transaction broadcasting and wallet monitoring
ā ā āāā utxoTransceiver.js # UTXO transceiver interface
ā āāā chaincode/ # Hyperledger Fabric chaincode
ā ā āāā custom/ # User-customized chaincodes
ā ā āāā templates/ # Chaincode templates
ā ā ā āāā default/ # Default chaincode template
ā ā ā āāā merchant-fee/ # Merchant fee chaincode template
ā ā āāā chaincodeManager.js # Chaincode management
ā āāā config/ # Configuration management
ā āāā hyperledger/ # Hyperledger Fabric integration
ā āāā wallet/ # Wallet management
ā āāā index.js # Main entry point
āāā transceivers/ # Transceiver modules
ā āāā utxo-transceiver.js # Generic UTXO transceiver implementation
ā āāā mock-transceiver.js # Mock transceiver for testing
ā āāā README.md # Transceiver documentation
āāā API.md # API documentation
āāā config.json # Configuration file (created from template)
āāā .env # Environment variables (created from template)
āāā .env.example # Environment variables template
āāā package.json # Project dependencies
āāā setup.sh # Setup script
āāā README.md # This file
FractaLedger provides a RESTful API for interacting with the system. See API.md for complete API documentation. Here are some example endpoints:
# Wallet Management
POST /api/wallets - Register a new wallet
GET /api/wallets - List all registered wallets
# Internal Wallet Management
POST /api/internal-wallets - Create a new internal wallet
GET /api/internal-wallets - List all internal wallets
GET /api/internal-wallets/:id/balance - Get the balance of an internal wallet
# Transactions
POST /api/transactions/withdraw - Initiate a withdrawal
GET /api/transactions - List all transactions
POST /api/transactions/broadcast - Broadcast a transaction
# Wallet Monitoring
POST /api/wallets/:id/monitor - Start monitoring a wallet address
DELETE /api/wallets/:id/monitor - Stop monitoring a wallet address
GET /api/wallets/:id/transactions - Get transaction history for a wallet
# Chaincode Management
GET /api/chaincode/templates - List available chaincode templates
POST /api/chaincode/custom - Create a custom chaincode
PUT /api/chaincode/custom/:id - Update a custom chaincode
POST /api/chaincode/custom/:id/deploy - Deploy a custom chaincode
Internal wallet transfers allow you to move funds between internal wallets that are mapped to the same primary on-chain wallet without requiring on-chain transactions. This feature is particularly useful for:
POST /api/transactions/internal-transfer
{
"fromInternalWalletId": "internal_wallet_1",
"toInternalWalletId": "internal_wallet_2",
"amount": 0.1,
"memo": "Payment for services" // Optional
}
Internal transfers are processed entirely within the Hyperledger Fabric ledger and do not create on-chain transactions. This makes them:
Base wallet protection ensures that the primary on-chain wallet always has sufficient funds to cover all internal wallets. This is achieved through:
To enable base internal wallet creation, add the following to your configuration file:
"baseInternalWallet": {
"namePrefix": "base_wallet_",
"description": "Represents excess funds in the primary on-chain wallet",
"createOnInitialization": true
}
The base internal wallet follows this naming convention:
{namePrefix}{blockchain}_{primaryWalletName}
For example, for a Bitcoin primary wallet named "btc_wallet_1", the base internal wallet would be named:
base_wallet_bitcoin_btc_wallet_1
GET /api/wallets/:blockchain/:name/read-only
Response:
{
"blockchain": "bitcoin",
"name": "btc_wallet_1",
"address": "bc1q...",
"balance": 1.5,
"aggregateInternalBalance": 1.2,
"excessBalance": 0.3,
"baseInternalWalletId": "base_wallet_bitcoin_btc_wallet_1"
}
This endpoint provides information about the primary wallet, including the aggregate balance of all internal wallets, the excess balance, and the ID of the base internal wallet.
FractaLedger includes a robust balance reconciliation system that ensures the integrity of your wallet balances. This feature verifies that the sum of all internal wallet balances matches the actual on-chain balance of the primary wallet.
Configure balance reconciliation in your config.json file:
"balanceReconciliation": {
"strategy": "afterTransaction",
"scheduledFrequency": 3600000,
"warningThreshold": 0.00001,
"strictMode": false
}
afterTransaction: Check after each transactionscheduled: Check at regular intervalsboth: Use both strategies# Reconciliation Configuration
GET /api/reconciliation/config - Get reconciliation configuration
# Manual Reconciliation
POST /api/reconciliation/wallet/:blockchain/:name - Reconcile a specific wallet
POST /api/reconciliation/all - Reconcile all wallets
# Discrepancy Management
GET /api/reconciliation/discrepancies - List all balance discrepancies
POST /api/reconciliation/discrepancies/:id/resolve - Resolve a discrepancy
When a discrepancy is detected, it's recorded in the ledger with details about the difference. Administrators can review and resolve discrepancies through the API, providing a resolution description that explains the cause and action taken.
FractaLedger includes a structured messaging system for API responses that provides clear, consistent, and informative feedback to clients. This system categorizes messages by type and severity, making it easier to handle responses programmatically.
API responses include both the requested data and any relevant messages:
{
"data": {
"success": true,
"transfer": {
"id": "transfer_123",
"fromWalletId": "internal_wallet_1",
"toWalletId": "internal_wallet_2",
"amount": 0.1,
"timestamp": "2025-03-13T12:00:00Z"
}
},
"messages": [
{
"type": "info",
"code": "INFO_001",
"message": "Internal transfer processed successfully",
"data": {
"fromWalletId": "internal_wallet_1",
"toWalletId": "internal_wallet_2",
"amount": 0.1
},
"timestamp": "2025-03-13T12:00:00Z"
},
{
"type": "warning",
"code": "WARN_001",
"message": "Primary wallet balance is low",
"data": {
"blockchain": "bitcoin",
"primaryWalletName": "btc_wallet_1",
"primaryWalletBalance": 1.2,
"aggregateInternalBalance": 1.1
},
"timestamp": "2025-03-13T12:00:00Z"
}
]
}
Each message includes a unique code that can be used for programmatic handling:
This messaging system makes it easier to build robust client applications that can handle both successful operations and various error conditions in a consistent way.
FractaLedger allows you to customize the smart contract logic for fund distribution, fee structures, and withdrawal management. The system provides two main ways to customize smart contracts:
src/chaincode/custom directory.FractaLedger comes with two chaincode templates:
You can create a custom chaincode based on one of these templates and then customize it to fit your specific needs.
Merchant Fee Collection: Take a percentage fee for facilitating cryptocurrency transfers between customers and merchants.
Employee Payment System: Distribute funds to employees based on predefined rules and schedules.
Investment Fund: Manage fractional ownership of cryptocurrency investments with custom distribution rules.
# Start the system in development mode
npm run dev
# Run tests
npm test
# Build the project for production
npm run build
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
FractaLedger provides several import paths for accessing specific functionality:
// Import the entire package
const fractaledger = require('fractaledger');
// Import specific modules
const { BlockchainConnector } = require('fractaledger/blockchain');
const { initializeWalletManager } = require('fractaledger/wallet');
const { SPVTransceiver } = require('fractaledger/transceivers');
const { startApiServer } = require('fractaledger/api');
// Import the entire package
import fractaledger from 'fractaledger';
// Import specific modules
import { BlockchainConnector } from 'fractaledger/blockchain';
import { initializeWalletManager } from 'fractaledger/wallet';
import { SPVTransceiver } from 'fractaledger/transceivers';
import { startApiServer } from 'fractaledger/api';
FractaLedger includes TypeScript definitions for better IDE support and type checking. When using TypeScript, you'll get autocompletion and type checking for all FractaLedger APIs:
import { BlockchainConnector } from 'fractaledger/blockchain';
import {
WalletConfig,
TransactionOptions,
CreateTransactionOptions,
SendTransactionOptions
} from 'fractaledger/blockchain';
// Create a blockchain connector with proper type checking
const config: WalletConfig = {
name: 'btc_wallet_1',
network: 'mainnet',
walletAddress: 'bc1q...',
secretEnvVar: 'BTC_WALLET_1_SECRET',
transceiver: {
method: 'callback',
callbackModule: './transceivers/utxo-transceiver.js'
}
};
const connector = new BlockchainConnector('bitcoin', config);
// Create a transaction with proper type checking
const createOptions: CreateTransactionOptions = {
opReturn: 'Hello, world!',
feeRate: 2
};
const transaction = await connector.createTransaction(inputs, outputs, createOptions);
// Send a transaction with proper type checking
const sendOptions: SendTransactionOptions = {
fee: 10000,
feeRate: 2,
utxos: inputs,
opReturn: 'Hello, world!'
};
const result = await connector.sendTransaction('bc1q...', 0.1, sendOptions);
FractaLedger provides specialized interfaces for different transaction operations:
TransactionOptions: General interface for transaction operations
opReturn?: Optional OP_RETURN datafee?: Optional transaction feefeeRate?: Optional fee rate in satoshis per byteutxos: Required UTXOs to use for the transactionCreateTransactionOptions: Interface for the createTransaction method
opReturn?: Optional OP_RETURN datafee?: Optional transaction feefeeRate?: Optional fee rate in satoshis per byteutxos?: Optional UTXOs to use for the transactionSendTransactionOptions: Interface for the sendTransaction method
opReturn?: Optional OP_RETURN datafee: Required transaction feefeeRate: Required fee rate in satoshis per byteutxos: Required UTXOs to use for the transactionWhen working with optional properties in TypeScript (marked with ?), you may encounter type compatibility issues. In these cases, you can use type assertions to tell TypeScript that you know what you're doing:
const sendOptions = {
fee: 10000,
feeRate: 2,
utxos: inputs,
opReturn: 'Hello, world!'
};
// Use type assertion when TypeScript has trouble with complex interfaces
const result = await connector.sendTransaction('bc1q...', 0.1, sendOptions as any);
For more detailed information about TypeScript support, see PackageExportsImplementation.md.
FractaLedger is regularly updated to address security vulnerabilities. Version 1.0.5 includes important security fixes for:
For detailed information about security updates, see SECURITY_UPDATES.md.
FractaLedger provides comprehensive documentation across various files. Here's a complete list of documentation files available in the project:
FAQs
A configurable off-chain UTXO management system that enables fractional ownership, secure fund distribution, and seamless on-chain interactions across multiple blockchains.
The npm package fractaledger receives a total of 1 weekly downloads. As such, fractaledger popularity was classified as not popular.
We found that fractaledger demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.