@x402nano/helper

Helper module for Nano x402 Clients, Resource Servers and Facilitators

Used by scheme implementations on nano:* family, e.g. exact.

Features

• Generate, sign and prepare Nano send blocks
• Proof-of-Work (PoW) generation via RPC or custom generator
• Account info retrieval (RPC account_info)
• Block publishing (RPC process)
• Balance calculation & insufficient funds protection
• Configurable RPC & Proof-of-Work generation endpoints
• Before/after Proof-of-Work generation hooks (for logging, etc...)
• Clean error handling with descriptive codes

Installation

TypeScript

npm install @x402nano/helper

Example Usage

TypeScript

// ** Usage of Helper module within a Facilitator that supports the exact scheme on nano:* family **

import { x402Facilitator } from '@x402/core/facilitator'
import { ExactNanoScheme } from '@x402nano/exact/facilitator'
import { Helper } from '@x402nano/helper' // Helper

// Create x402 core Facilitator instance
const facilitator = new x402Facilitator()

// Create instance of Helper module and configure with Nano RPC endpoint
const helper = new Helper({
  NANO_RPC_URL: 'https://example-nano-rpc-endpoint.com/rpc',
})

// Pass Helper module instance into scheme instance.
// Scheme code can now access the Nano network through use
// of the configured Helper module instance.
const exactNanoScheme = new ExactNanoScheme(helper)

// Register the scheme loaded with Helper module instance into the Facilitator instance
facilitator.register('nano:mainnet', exactNanoScheme)

💡 Detailed examples of usage can be viewed in the /examples/ folder for the x402nano exact scheme.

API

Configuration

TypeScript

Pass configuration values directly to the constructor:

const helper = new Helper({
  NANO_RPC_URL: 'https://...'                   // Required
  NANO_WORK_GENERATION_URL: 'https://...'       // Optional, defaults to NANO_RPC_URL
  NANO_ACCOUNT_PRIVATE_KEY: 'FEEDFACE1234...'   // Required if using generateSendBlock
})

Or you can use the following setters:

const helper = new Helper()

helper.setNanoRpcUrl('https://example-nano-rpc-endpoint.com/rpc')
helper.setNanoWorkGenerationUrl('https://example-nano-work-generation-endpoint.com/rpc')
helper.setNanoAccountPrivateKey('FEEDFACE1234...')

The setCustomWorkGenerator setter takes a function as a parameter. This function must accept as a parameter the hash you wish to generate Proof-of-Work for, and must return the work computed.

helper.setCustomWorkGenerator(function (hash: string): string {
  const work = // ...perform work generation using "hash" parameter here...
  return work
})

Error Codes

Errors include one of the following codes, as well as more descriptive debugging information.

Project Structure

TypeScript

helper/src/typescript/
├── index.ts                 # Main code for Helper
└── common.ts                # Shared constants used by Helper code and tests

helper/src/typescript/test
└── index.test.ts            # Test script (run with `npm run test`)

Development

TypeScript

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm run test

Contributing

We welcome developers to submit implementations of the Helper module in other languages e.g. Python, Go, etc...

Join the x402 Nano Discord for coordination and discussion!

Security Notes 🚨

• This is new software and hasn't yet been deployed heavily in production environments yet. Please test with small amounts of Nano only! The authors and contributors shall not be held liable for any use of this software's functionality, intentional or unintentional, that leads to an undesired lose of funds.
• Never commit private keys to version control
• Consider calling clearNanoAccountPrivateKey to clear private key in long-running processes

Related Projects

• @x402nano/exact – Implementation of exact scheme for fixed-amount Nano (XNO) payments over x402 protocol
• x402.org – Official x402 protocol website
• nano.org – Official Nano website

License

MIT