ono-web

JavaScript API for the ONO blockchain. Create HD wallets, build and submit signed transactions, and subscribe to live events from a core node — from both Node.js and the browser.

Requires an ono-core node >= 1.2.5 (this version introduced the domain-separated transaction hash). On Node.js, version 18+ is needed (the library relies on the global fetch).

Install

npm install ono-web

const { wallet, transaction, ServerClient, BrowserClient } = require('ono-web');

Quick start

const { wallet, transaction } = require('ono-web');

// 1. Create a wallet (or restore one from an existing mnemonic)
const { mnemonic, seed } = await wallet.newWalletData();
const hdWallet = wallet.hdWallet(seed);
const keyPair = wallet.generateKeyPair(hdWallet, 0);

// 2. Build and sign a transaction
const tx = transaction.generateTransaction(
    recipientPublicKeyHex, // 'to' address (compressed public key, hex)
    1.5, // amount
    {
        publicKey: keyPair.publicKey.toString('hex'),
        privateKey: keyPair.privateKey.toString('hex'),
    },
);

// 3. Submit it to the core node
const result = await transaction.sendTransaction(tx);

// 4. Look it up later by hash
const confirmed = await transaction.getTransactionByHash(tx.hash);

Wallet

Keys are derived with BIP39/BIP32 at the path m/44'/2909'/0'/0/<index>. An address on ONO is the account's compressed public key in hex.

| Function | Description | | ----------------------------------------- | -------------------------------------------------------------------------------------- | | wallet.newWalletData() | Generates a fresh mnemonic; resolves to { mnemonic, seed } (seed as hex). | | wallet.walletDataFromMnemonic(mnemonic) | Restores { mnemonic, seed } from an existing BIP39 mnemonic. | | wallet.hdWallet(seed) | Builds an HD wallet (hdkey instance) from a hex seed. | | wallet.generateKeyPair(hdWallet, index) | Derives the key pair at account index index. Has publicKey / privateKey buffers. |

Keep the mnemonic (and seed) secret — either one fully controls the wallet's funds.

Transactions

const { transaction } = require('ono-web');

// Optional configuration — defaults shown:
transaction.setCoreHost(new URL('http://core.ono.gg'));
transaction.setNetwork('mainnet'); // or 'testnet'

| Function | Description | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | transaction.setCoreHost(url) | URL of the core node used by sendTransaction / getTransactionByHash. | | transaction.setNetwork(network) | 'mainnet' (default) or 'testnet'. Mixed into the transaction hash, so it must match the node's network — a hash made for the wrong network is rejected. | | transaction.calculateFee(amount) | Fee preview: 0.01% of the amount, capped at 0.01. | | transaction.generateTransaction(to, amount, keyPair) | Builds, hashes, and signs a transaction locally. keyPair is { publicKey, privateKey } as hex strings. Returns the complete transaction object. | | transaction.sendTransaction(tx) | POSTs the transaction to the node (/transaction/init) and resolves with the node's JSON response. | | transaction.getTransactionByHash(hash) | Fetches a transaction by hash (/transaction/by-hash/:hash), including its block reference once mined. |

A generated transaction looks like:

{
    from: '03...',      // sender public key (hex)
    to: '02...',        // recipient public key (hex)
    amount: 1.5,
    fee: 0.00015,
    timestamp: 1786019896,          // seconds
    hash: '7206734a...',            // sha256 over the domain-separated preimage
    signature: 'feee20f1...'        // canonical (low-S) secp256k1 ECDSA over the hash
}

Live events (WebSocket)

Two clients implement the same subscription protocol; pick the one for your environment:

• ServerClient — Node.js, built on the ws package.
• BrowserClient — browsers, built on the native WebSocket.

Both keep the connection alive automatically (a ping every 30 seconds).

const { ServerClient } = require('ono-web'); // or BrowserClient in the browser

const client = new ServerClient('http://core.ono.gg'); // http(s) is converted to ws(s)

client.subscribe(
    (message, client) => {
        switch (message.type) {
            case 'NEW_TRANSACTION': // message.data: a transaction entering the mempool
            case 'NEW_BLOCK': // message.data: a freshly forged block
            case 'STATUS': // message.data: { lastBlockId, lastBlockHash }, sent on connect and every 30s
                console.log(message.type, message.data);
                break;
        }
    },
    (error) => console.error('bad message', error),
);

// later
client.disconnect();

Messages arrive as { type, data }. The ones relevant to API consumers are NEW_TRANSACTION, NEW_BLOCK, and STATUS (core >= 1.2.5); the node may also send peer-to-peer housekeeping types (PONG, PEERS_REQUEST, ...) which can simply be ignored.

Compatibility notes

• ono-web >= 1.1.0 requires ono-core >= 1.2.5. The transaction hash preimage changed in core 1.2.5 (domain-separated: transaction|<network>|amount=..|from=..|timestamp=..|to=..); older cores reject transactions built by this version and vice versa.
• Signatures are canonical (low-S) ECDSA over secp256k1, as required by core >= 1.2.5.
• When talking to a node running with TESTNET=true, call transaction.setNetwork('testnet') before generating transactions.

License

MIT