Altius JavaScript SDK

A pure JavaScript SDK for signing and sending Altius USD multi-token transactions. Supports the USD Multi-Token fee model (0x7a transaction type).

Installation

npm install @altiuslabs/tx-sdk

Usage

Quick Start

import { TxClient, generate_private_key } from '@altiuslabs/tx-sdk';
import { USDA_ADDRESS } from '@altiuslabs/tx-sdk';

// Generate a new wallet
const privateKey = generate_private_key();

// Create a client
const client = new TxClient(privateKey, 'https://rpc.altius.xyz', USDA_ADDRESS);

// Transfer USDA
const txHash = await client.transfer_usda(recipient, 1_000_000); // 1 USD
console.log('Transaction hash:', txHash);

Configuration

import { TxClientBuilder, BASE_FEE_ATTO, DEFAULT_GAS_LIMIT } from '@altiuslabs/tx-sdk';

const client = new TxClientBuilder(privateKey, 'https://rpc.altius.xyz')
  .fee_token('0xa1700000000000000000000000000000000000001')
  .base_fee(BASE_FEE_ATTO)
  .gas_limit(DEFAULT_GAS_LIMIT)
  .build();

Transaction Operations

// Get account balance
const balance = await client.fee_token_balance(address);

// Send ERC20 transfer
const { tx_hash } = await client.send_erc20_transfer(
  token_address,
  recipient,
  BigInt(1_000_000_000_000_000000) // 1 token with 18 decimals
);

// Send and wait for receipt
const receipt = await client.send_and_wait(tx, 60000);

API Reference

Wallet & Signing

generate_private_key() => string

Generate a new random private key.

const privateKey = generate_private_key();

private_key_to_address(privateKey: string) => string

Derive address from private key.

const address = private_key_to_address('0x...');

Wallet

Wallet class for local transaction signing.

import { Wallet } from '@altiuslabs/tx-sdk';

// Create wallet from private key
const wallet = new Wallet('0x...');

// Get address
console.log(wallet.address); // '0x...'

// Sign hash
const signature = await wallet.sign_hash('0x...');

Transaction Builder

create_transaction() => TxBuilder

Create a new transaction builder.

import { create_transaction } from '@altiuslabs/tx-sdk';

const tx = create_transaction()
  .chain_id(1)
  .nonce(0)
  .gas_limit(21000)
  .to('0x...')
  .value(0)
  .data('0x...')
  .fee_token('0xa1700000000000000000000000000000000000001')
  .max_fee_per_gas_usd(50000000000);

TxBuilder Methods

| Method | Description | |--------|-------------| | .chain_id(id) | Set chain ID | | .nonce(nonce) | Set transaction nonce | | .gas_limit(limit) | Set gas limit | | .to(address) | Set recipient address | | .value(amount) | Set transaction value (in wei) | | .data(calldata) | Set input data | | .max_priority_fee_per_gas(gas) | Set max priority fee per gas | | .max_fee_per_gas(gas) | Set max fee per gas | | .fee_token(address) | Set fee token address | | .fee_payer(address) | Set fee payer address (optional, defaults to sender) | | .max_fee_per_gas_usd(usd) | Set max fee per gas in USD attodollars | | .fee_payer_signature(signature) | Set fee payer signature | | .erc20_transfer(token, to, amount) | Build ERC20 transfer | | .build() | Build transaction object | | .signature_hash() | Compute signature hash | | .sign(wallet) | Sign transaction with wallet |

fee_payer_signature_hash(tx: object, sender: string) => string

Calculate the hash that fee_payer should sign.

RPC Client

create_rpc_client(url: string) => RpcClient

Create an RPC client.

import { create_rpc_client } from '@altiuslabs/tx-sdk';

const rpc = create_rpc_client('https://rpc.altius.xyz');

RpcClient Methods

| Method | Description | |--------|-------------| | .get_chain_id() | Get chain ID | | .get_block_number() | Get latest block number | | .get_balance(address) | Get native ETH balance | | .get_nonce(address) | Get transaction count (nonce) | | .get_code(address) | Get contract code at address | | .call(call_object) | Execute contract call | | .send_raw_transaction(tx) | Send signed transaction | | .get_transaction_receipt(hash) | Get transaction receipt | | .wait_for_receipt(hash, timeout_ms) | Wait for transaction to be mined | | .get_erc20_balance(token, owner) | Get ERC20 token balance |

Nonce Manager

create_nonce_manager(rpc: RpcClient, address: string) => NonceManager

Create a nonce manager.

import { create_nonce_manager } from '@altiuslabs/tx-sdk';

const nm = create_nonce_manager(rpc, address);

NonceManager Methods

| Method | Description | |--------|-------------| | .get_nonce() | Get current nonce | | .get_and_increment_nonce() | Get and increment nonce | | .reset_nonce() | Reset nonce cache |

High-Level Client

create_tx_client(privateKey: string, rpcUrl: string, feeToken: string) => TxClient

Create a high-level transaction client.

import { create_tx_client } from '@altiuslabs/tx-sdk';
import { USDA_ADDRESS } from '@altiuslabs/tx-sdk';

const client = create_tx_client(privateKey, 'https://rpc.altius.xyz', USDA_ADDRESS);

TxClientBuilder

import { TxClientBuilder } from '@altiuslabs/tx-sdk';

const client = new TxClientBuilder(privateKey, 'https://rpc.altius.xyz')
  .fee_token(USDA_ADDRESS)
  .base_fee(50000000000)
  .gas_limit(100000)
  .build();

TxClient Methods

| Method | Description | |--------|-------------| | .address() | Get wallet address | | .chain_id() | Get chain ID | | .get_nonce() | Get current nonce | | .build_erc20_transfer(token, recipient, amount) | Build ERC20 transfer | | .sign(tx) | Sign transaction | | .send(tx) | Send transaction | | .send_and_wait(tx, timeout_ms) | Send and wait for receipt | | .send_erc20_transfer(token, recipient, amount) | Send ERC20 transfer | | .transfer_usda(recipient, amount_micro) | Transfer USDA (amount in microdollars) | | .fee_token_balance(address) | Get fee token balance | | .native_balance(address) | Get native ETH balance | | .reset_nonce() | Reset nonce cache |

Utilities

keccak256(data: string | Buffer) => string

Compute keccak256 hash.

import { keccak256 } from '@altiuslabs/tx-sdk';

const hash = keccak256('0x...');

pad_hex(hex: string, bytes: number) => string

Pad hex string to specified length.

import { pad_hex } from '@altiuslabs/tx-sdk';

pad_hex('0x1234', 32); // '0x0000000000000000000000000000000000000000000000000000000000001234'

num_to_hex(num: number, bytes?: number) => string

Convert number to padded hex.

import { num_to_hex } from '@altiuslabs/tx-sdk';

num_to_hex(123, 32); // '0x000000000000000000000000000000000000000000000000000000000000007b'

rlp_encode(items: array) => string

RLP encode an array.

import { rlp_encode } from '@altiuslabs/tx-sdk';

const encoded = rlp_encode([1, 2, 3]);

computeFeeTokenAddress(creator: string, salt: string) => { address: string, index: bigint }

Compute deterministic fee token address.

import { computeFeeTokenAddress } from '@altiuslabs/tx-sdk';

const { address, index } = computeFeeTokenAddress(creator, salt);

is_fee_token_prefix(address: string) => boolean

Check if address has fee token prefix (0xa170...).

import { is_fee_token_prefix } from '@altiuslabs/tx-sdk';

is_fee_token_prefix('0xa1700000000000000000000000000000000000001'); // true

is_valid_fee_token_address(address: string) => boolean

Check if address is valid fee token (has prefix and not zero).

import { is_valid_fee_token_address } from '@altiuslabs/tx-sdk';

is_valid_fee_token_address('0xa1700000000000000000000000000000000000001'); // true

is_index_reserved(index: bigint | number) => boolean

Check if index is reserved (index < 256).

import { is_index_reserved } from '@altiuslabs/tx-sdk';

is_index_reserved(100n); // true
is_index_reserved(300n); // false

Constants

| Constant | Description | |----------|-------------| | USDA_ADDRESS | USDA Fee Token: 0xa1700000000000000000000000000000000000001 | | FEE_TOKEN_FACTORY_ADDRESS | Fee Token Factory: 0xa170000000000000000000000000000000000000 | | FEE_MANAGER_ADDRESS | Fee Manager: 0xFE00000000000000000000000000000000000001 | | ZERO_ADDRESS | Zero address: 0x0000000000000000000000000000000000000000 | | BASE_FEE_ATTO | Base fee: 50,000,000,000 (50 G-attodollars/gas) | | DEFAULT_MAX_FEE_PER_GAS | Default max fee: 100,000,000,000 | | DEFAULT_GAS_LIMIT | Default gas limit: 100,000 | | FAUCET_AMOUNT_MICRO | Faucet amount: 100,000,000 microdollars | | FAUCET_AMOUNT_WEI | Faucet amount: 100,000,000,000,000,000,000 wei | | TRANSFER_AMOUNT_MICRO | Default transfer: 10,000,000 microdollars | | TRANSFER_AMOUNT_WEI | Default transfer: 10,000,000,000,000,000,000 wei | | RESERVED_THRESHOLD | Reserved threshold: 256 | | FAUCET_FEE_TOKEN | Default faucet fee token (same as USDA_ADDRESS) |

Security

IMPORTANT: Private keys never leave the client. All signing happens locally.

// WRONG - never send private key to server
await fetch('/api/send', { body: { private_key: "0x..." } });

// CORRECT - sign locally, send raw transaction
const signedTx = await client.sign(tx);
await rpcClient.send('eth_sendRawTransaction', [signedTx.raw_transaction]);

Transaction Type

This SDK supports the USD Multi-Token fee model (0x7a transaction type):

• fee_token: ERC20 token address used for gas payment
• fee_payer: Account paying the fee (optional, defaults to sender)
• max_fee_per_gas_usd_attodollars: Max gas price in USD attodollars/gas

License

MIT