@altiuslabs/tx-sdk 0.1.3

package/README.md

@@ -0,0 +1,105 @@
+# 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
+
+```bash
+npm install @altius/tx-sdk
+```
+
+## Usage
+
+### Quick Start
+
+```javascript
+import { TxClient, generate_private_key } from '@altius/tx-sdk';
+import { USDA_ADDRESS } from '@altius/tx-sdk/constants';
+
+// 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
+
+```javascript
+import { TxClientBuilder, BASE_FEE_ATTO, DEFAULT_GAS_LIMIT } from '@altius/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
+
+```javascript
+// 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
+
+### Core Classes
+
+- **TxClient** - High-level client for sending transactions
+- **Wallet** - Key management and address derivation
+- **RpcClient** - JSON-RPC interaction
+- **NonceManager** - Nonce management
+- **TxBuilder** - Transaction building
+
+### Constants
+
+```javascript
+import {
+  USDA_ADDRESS,
+  FEE_TOKEN_FACTORY_ADDRESS,
+  FEE_MANAGER_ADDRESS,
+  ALT_FEE_TOKEN_ADDRESS,
+  BASE_FEE_ATTO,
+  DEFAULT_GAS_LIMIT,
+} from '@altius/tx-sdk/constants';
+```
+
+## Security
+
+**IMPORTANT**: Private keys never leave the client. All signing happens locally.
+
+```javascript
+// 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

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@altiuslabs/tx-sdk",
+  "version": "0.1.3",
+  "description": "SDK for signing and sending Altius USD multi-token transactions",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./constants": "./src/constants.js"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "altius",
+    "ethereum",
+    "sdk",
+    "constants",
+    "signer"
+  ],
+  "dependencies": {
+    "js-sha3": "^0.9.3",
+    "noble-secp256k1": "^1.2.14",
+    "rlp": "^3.0.0"
+  },
+  "author": "",
+  "license": "MIT"
+}

package/src/client.js

@@ -0,0 +1,263 @@
+/**
+ * High-level client for sending Altius transactions
+ */
+
+import { TxBuilder } from './transaction.js';
+import { Wallet } from './wallet.js';
+import { RpcClient } from './rpc.js';
+import { NonceManager } from './nonce.js';
+import { USDA_ADDRESS, DEFAULT_GAS_LIMIT, BASE_FEE_ATTO } from './constants.js';
+
+/**
+ * TxClient - High-level client for sending Altius transactions
+ */
+export class TxClient {
+  /**
+   * Create a new transaction client
+   * @param {string} private_key - Private key as 0x-prefixed hex
+   * @param {string} rpc_url - JSON-RPC endpoint URL
+   * @param {string} fee_token - Fee token address (0x-prefixed hex)
+   */
+  constructor(private_key, rpc_url, fee_token) {
+    this.wallet = new Wallet(private_key);
+    this.rpc = new RpcClient(rpc_url);
+    this.nonce_manager = new NonceManager(this.rpc, this.wallet.address);
+    this.fee_token = fee_token;
+    this.base_fee = BASE_FEE_ATTO;
+    this.gas_limit = DEFAULT_GAS_LIMIT;
+  }
+
+  /**
+   * Get the wallet address
+   * @returns {string}
+   */
+  get address() {
+    return this.wallet.address;
+  }
+
+  /**
+   * Get the chain ID
+   * @returns {Promise<number>}
+   */
+  async chain_id() {
+    return this.rpc.get_chain_id();
+  }
+
+  /**
+   * Get current nonce
+   * @returns {Promise<number>}
+   */
+  async get_nonce() {
+    return this.nonce_manager.get_nonce();
+  }
+
+  /**
+   * Build an ERC20 transfer transaction
+   * @param {string} token - Token address
+   * @param {string} recipient - Recipient address
+   * @param {BigInt} amount - Amount in wei
+   * @returns {Promise<object>}
+   */
+  async build_erc20_transfer(token, recipient, amount) {
+    const chain_id = await this.chain_id();
+    const nonce = await this.nonce_manager.get_and_increment_nonce();
+
+    return new TxBuilder()
+      .chain_id(chain_id)
+      .nonce(nonce)
+      .gas_limit(this.gas_limit)
+      .erc20_transfer(token, recipient, amount)
+      .fee_token(this.fee_token)
+      .max_fee_per_gas_usd(BigInt(this.base_fee) * 2n)
+      .build();
+  }
+
+  /**
+   * Send an ERC20 transfer transaction
+   * @param {string} token - Token address
+   * @param {string} recipient - Recipient address
+   * @param {BigInt} amount - Amount in wei
+   * @returns {Promise<{tx: object, tx_hash: string}>}
+   */
+  async send_erc20_transfer(token, recipient, amount) {
+    const tx = await this.build_erc20_transfer(token, recipient, amount);
+    const signed = await this.sign(tx);
+    const tx_hash = await this.rpc.send_raw_transaction(signed.raw_transaction);
+    return { tx, tx_hash };
+  }
+
+  /**
+   * Sign a transaction without sending
+   * @param {object} tx - Transaction object
+   * @returns {Promise<object>}
+   */
+  async sign(tx) {
+    const tx_builder = this._tx_to_builder(tx);
+    return tx_builder.sign(this.wallet);
+  }
+
+  /**
+   * Send a pre-built transaction
+   * @param {object} tx - Transaction object
+   * @returns {Promise<string>} Transaction hash
+   */
+  async send(tx) {
+    const signed = await this.sign(tx);
+    return this.rpc.send_raw_transaction(signed.raw_transaction);
+  }
+
+  /**
+   * Send a transaction and wait for receipt
+   * @param {object} tx - Transaction object
+   * @param {number} timeout_ms - Timeout in milliseconds
+   * @returns {Promise<object>} Transaction receipt
+   */
+  async send_and_wait(tx, timeout_ms = 60000) {
+    const tx_hash = await this.send(tx);
+    return this.rpc.wait_for_receipt(tx_hash, timeout_ms);
+  }
+
+  /**
+   * Transfer USDA (fee token)
+   * @param {string} recipient - Recipient address
+   * @param {number} amount_micro - Amount in microdollars
+   * @returns {Promise<string>} Transaction hash
+   */
+  async transfer_usda(recipient, amount_micro) {
+    const { tx_hash } = await this.send_erc20_transfer(
+      this.fee_token,
+      recipient,
+      BigInt(amount_micro)
+    );
+    return tx_hash;
+  }
+
+  /**
+   * Transfer USDA and wait for confirmation
+   * @param {string} recipient - Recipient address
+   * @param {number} amount_micro - Amount in microdollars
+   * @param {number} timeout_ms - Timeout in milliseconds
+   * @returns {Promise<object>} Transaction receipt
+   */
+  async transfer_usda_and_wait(recipient, amount_micro, timeout_ms = 60000) {
+    const tx = await this.build_erc20_transfer(
+      this.fee_token,
+      recipient,
+      BigInt(amount_micro)
+    );
+    return this.send_and_wait(tx, timeout_ms);
+  }
+
+  /**
+   * Get fee token balance for an address
+   * @param {string} address - Address to check
+   * @returns {Promise<bigint>}
+   */
+  async fee_token_balance(address) {
+    return this.rpc.get_erc20_balance(this.fee_token, address);
+  }
+
+  /**
+   * Get native balance for an address
+   * @param {string} address - Address to check
+   * @returns {Promise<bigint>}
+   */
+  async native_balance(address) {
+    return this.rpc.get_balance(address);
+  }
+
+  /**
+   * Reset the nonce cache (useful after errors)
+   */
+  reset_nonce() {
+    this.nonce_manager.reset_nonce();
+  }
+
+  /**
+   * Convert tx object back to builder for signing
+   * @private
+   */
+  _tx_to_builder(tx) {
+    const builder = new TxBuilder()
+      .chain_id(tx.chain_id)
+      .nonce(tx.nonce)
+      .gas_limit(tx.gas_limit)
+      .to(tx.to)
+      .value(tx.value)
+      .data(tx.data)
+      .fee_token(tx.fee_token)
+      .fee_payer(tx.fee_payer)
+      .fee_payer_signature(tx.fee_payer_signature);
+
+    if (tx.max_fee_per_gas_usd_attodollars) {
+      builder.max_fee_per_gas_usd(tx.max_fee_per_gas_usd_attodollars);
+    }
+
+    return builder;
+  }
+}
+
+/**
+ * TxClientBuilder - Builder for TxClient
+ */
+export class TxClientBuilder {
+  constructor(private_key, rpc_url) {
+    this.private_key = private_key;
+    this.rpc_url = rpc_url;
+    this.fee_token = USDA_ADDRESS;
+    this.base_fee = BASE_FEE_ATTO;
+    this.gas_limit = DEFAULT_GAS_LIMIT;
+  }
+
+  /**
+   * Set fee token address
+   * @param {string} fee_token
+   * @returns {TxClientBuilder}
+   */
+  fee_token(fee_token) {
+    this.fee_token = fee_token;
+    return this;
+  }
+
+  /**
+   * Set base fee in attodollars
+   * @param {number} base_fee
+   * @returns {TxClientBuilder}
+   */
+  base_fee(base_fee) {
+    this.base_fee = base_fee;
+    return this;
+  }
+
+  /**
+   * Set gas limit
+   * @param {number} gas_limit
+   * @returns {TxClientBuilder}
+   */
+  gas_limit(gas_limit) {
+    this.gas_limit = gas_limit;
+    return this;
+  }
+
+  /**
+   * Build the TxClient
+   * @returns {TxClient}
+   */
+  build() {
+    const client = new TxClient(this.private_key, this.rpc_url, this.fee_token);
+    client.base_fee = this.base_fee;
+    client.gas_limit = this.gas_limit;
+    return client;
+  }
+}
+
+/**
+ * Create a new TxClient
+ * @param {string} private_key - Private key
+ * @param {string} rpc_url - RPC URL
+ * @param {string} fee_token - Fee token address
+ * @returns {TxClient}
+ */
+export function create_tx_client(private_key, rpc_url, fee_token) {
+  return new TxClient(private_key, rpc_url, fee_token);
+}

package/src/constants.js

@@ -0,0 +1,131 @@
+/**
+ * Altius SDK - JavaScript/TypeScript Constants
+ *
+ * This is the single source of truth for all address and configuration values
+ * used by:
+ * - Frontend (TypeScript)
+ * - Tests (JavaScript/Node.js)
+ * - Backend (via altius-tx-sdk)
+ *
+ * IMPORTANT: When modifying addresses or constants, update this file first,
+ * then propagate changes to other SDKs.
+ *
+ * This file is generated from altius-predeploy/src/addresses.rs
+ * Do not edit manually - update the source and regenerate.
+ */
+
+// ============================================================================
+// Address Constants
+// ============================================================================
+
+/**
+ * USDA Fee Token (ERC20) - Genesis Fee Token
+ * Address: 0xa1700000000000000000000000000000000000001 (index 1)
+ */
+export const USDA_ADDRESS = '0xa1700000000000000000000000000000000000001';
+
+/**
+ * Fee Token Factory
+ * Address: 0xa1700000000000000000000000000000000000000 (index 0)
+ */
+export const FEE_TOKEN_FACTORY_ADDRESS = '0xa1700000000000000000000000000000000000000';
+
+/**
+ * Fee Manager (Independent prefix)
+ * Address: 0xFE0000000000000000000000000000000000000001
+ */
+export const FEE_MANAGER_ADDRESS = '0xFE0000000000000000000000000000000000000001';
+
+/**
+ * Alternative fee token for testing (index 2)
+ */
+export const ALT_FEE_TOKEN_ADDRESS = '0xa170000000000000000000000000000000000002';
+
+/**
+ * Fee token prefix (10 bytes) for validation
+ */
+export const FEE_TOKEN_PREFIX = '0xa1700000';
+
+/**
+ * Zero address
+ */
+export const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+// Valid addresses for testing
+export const VALID_ADDRESSES = {
+  USDA: USDA_ADDRESS,
+  FACTORY: FEE_TOKEN_FACTORY_ADDRESS,
+  ALT_TOKEN: ALT_FEE_TOKEN_ADDRESS,
+};
+
+// Invalid addresses for testing
+export const INVALID_ADDRESSES = {
+  NO_PREFIX: '0x1234567890123456789012345678901234567890',
+  WETH: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+  ZERO: ZERO_ADDRESS,
+};
+
+// ============================================================================
+// Fee Configuration
+// ============================================================================
+
+/**
+ * Base fee in attodollars per gas (50 G-attodollars/gas)
+ */
+export const BASE_FEE_ATTO = 50_000_000_000;
+
+/**
+ * Default max fee per gas (2x base fee)
+ */
+export const DEFAULT_MAX_FEE_PER_GAS = 100_000_000_000;
+
+// ============================================================================
+// Token Configuration
+// ============================================================================
+
+/**
+ * Default faucet amount in microdollars (100 USDA)
+ */
+export const FAUCET_AMOUNT_MICRO = BigInt(100_000_000);
+
+/**
+ * Default faucet amount in token units (100 USDA with 18 decimals)
+ */
+export const FAUCET_AMOUNT_WEI = BigInt(100_000_000_000_000_000_000);
+
+/**
+ * Default transfer amount in microdollars (10 USDA)
+ */
+export const TRANSFER_AMOUNT_MICRO = BigInt(10_000_000);
+
+/**
+ * Default transfer amount in token units (10 USDA with 18 decimals)
+ */
+export const TRANSFER_AMOUNT_WEI = BigInt(10_000_000_000_000_000_000);
+
+// ============================================================================
+// Gas Configuration
+// ============================================================================
+
+/**
+ * Default gas limit for ERC20 transfers
+ */
+export const DEFAULT_GAS_LIMIT = 100_000;
+
+// ============================================================================
+// Validation Constants
+// ============================================================================
+
+/**
+ * Reserved address threshold (indices 0-255 are reserved)
+ */
+export const RESERVED_THRESHOLD = 256;
+
+// ============================================================================
+// Faucet Configuration
+// ============================================================================
+
+/**
+ * Default fee token for faucet (USDA)
+ */
+export const FAUCET_FEE_TOKEN = USDA_ADDRESS;

package/src/error.js

@@ -0,0 +1,44 @@
+/**
+ * Error types for Altius SDK
+ */
+
+export class AltiusError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AltiusError';
+  }
+}
+
+export class InvalidPrivateKeyError extends AltiusError {
+  constructor(message) {
+    super(message);
+    this.name = 'InvalidPrivateKeyError';
+  }
+}
+
+export class SigningError extends AltiusError {
+  constructor(message) {
+    super(message);
+    this.name = 'SigningError';
+  }
+}
+
+export class RpcError extends AltiusError {
+  constructor(message, code = -1) {
+    super(message);
+    this.name = 'RpcError';
+    this.code = code;
+  }
+}
+
+export class MissingFieldError extends AltiusError {
+  constructor(field) {
+    super(`${field} is required`);
+    this.name = 'MissingFieldError';
+    this.field = field;
+  }
+}
+
+// Re-export error classes for convenience
+export const Error = AltiusError;
+export const Result = AltiusError;

package/src/index.js

@@ -0,0 +1,29 @@
+/**
+ * Altius JavaScript SDK
+ *
+ * A pure JavaScript SDK for signing and sending Altius transactions.
+ * Supports the USD Multi-Token fee model (0x7a transaction type).
+ *
+ * IMPORTANT: Private keys never leave the client. All signing happens locally.
+ */
+
+// Error types
+export * from './error.js';
+
+// Wallet and signing
+export { Wallet, generate_private_key, private_key_to_address, sign_hash } from './wallet.js';
+
+// Transaction building
+export { TxBuilder, create_transaction, fee_payer_signature_hash } from './transaction.js';
+
+// RPC client
+export { RpcClient, create_rpc_client } from './rpc.js';
+
+// Nonce management
+export { NonceManager, create_nonce_manager } from './nonce.js';
+
+// High-level client
+export { TxClient, TxClientBuilder, create_tx_client } from './client.js';
+
+// Constants
+export * from './constants.js';

package/src/nonce.js

@@ -0,0 +1,83 @@
+/**
+ * Nonce manager for tracking and managing transaction nonces
+ */
+
+import { RpcClient } from './rpc.js';
+
+/**
+ * NonceManager - manages transaction nonces for an address
+ */
+export class NonceManager {
+  /**
+   * Create a new NonceManager
+   * @param {RpcClient} rpcClient - RPC client instance
+   * @param {string} address - Address to manage nonces for (0x-prefixed hex)
+   */
+  constructor(rpcClient, address) {
+    this.rpcClient = rpcClient;
+    this.address = address;
+    this.localNonce = null;
+  }
+
+  /**
+   * Get the current nonce (from local cache or RPC)
+   * @returns {Promise<number>}
+   */
+  async get_nonce() {
+    if (this.localNonce !== null) {
+      return this.localNonce;
+    }
+    const nonce = await this.rpcClient.get_nonce(this.address);
+    this.localNonce = Number(nonce);
+    return this.localNonce;
+  }
+
+  /**
+   * Get and increment the nonce (atomic operation)
+   * @returns {Promise<number>}
+   */
+  async get_and_increment_nonce() {
+    const nonce = await this.get_nonce();
+    this.localNonce = nonce + 1;
+    return nonce;
+  }
+
+  /**
+   * Reset the local nonce cache
+   */
+  async reset_nonce() {
+    this.localNonce = null;
+  }
+
+  /**
+   * Sync local nonce with on-chain state
+   * @returns {Promise<number>}
+   */
+  async sync_nonce() {
+    this.localNonce = null;
+    return this.get_nonce();
+  }
+
+  /**
+   * Advance nonce by a delta (for batch transactions)
+   * @param {number} delta - Amount to advance
+   * @returns {number}
+   */
+  advance_nonce(delta = 1) {
+    if (this.localNonce === null) {
+      throw new Error('Cannot advance nonce without first calling get_nonce()');
+    }
+    this.localNonce += delta;
+    return this.localNonce - delta;
+  }
+}
+
+/**
+ * Create a new NonceManager
+ * @param {RpcClient} rpcClient - RPC client instance
+ * @param {string} address - Address to manage nonces for
+ * @returns {NonceManager}
+ */
+export function create_nonce_manager(rpcClient, address) {
+  return new NonceManager(rpcClient, address);
+}

package/src/rpc.js

@@ -0,0 +1,155 @@
+/**
+ * RPC Client for Altius
+ */
+
+import { numToHex, padHex } from './utils.js';
+
+/**
+ * JSON-RPC client for communicating with Altius node
+ */
+export class RpcClient {
+  /**
+   * @param {string} url - RPC URL (e.g., http://localhost:8545)
+   */
+  constructor(url) {
+    this.url = url;
+    this.id = 0;
+  }
+
+  /**
+   * Make a JSON-RPC request
+   * @param {string} method - RPC method name
+   * @param {Array} params - Method parameters
+   * @returns {Promise<any>}
+   */
+  async request(method, params = []) {
+    const response = await fetch(this.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: ++this.id,
+        method,
+        params,
+      }),
+    });
+
+    const result = await response.json();
+
+    if (result.error) {
+      throw new Error(`RPC Error: ${result.error.message}`);
+    }
+
+    return result.result;
+  }
+
+  /**
+   * Get the chain ID
+   * @returns {Promise<number>}
+   */
+  async get_chain_id() {
+    const hex = await this.request('eth_chainId');
+    return parseInt(hex, 16);
+  }
+
+  /**
+   * Get transaction count (nonce) for an address
+   * @param {string} address - Address as 0x-prefixed hex
+   * @returns {Promise<number>}
+   */
+  async get_nonce(address) {
+    const hex = await this.request('eth_getTransactionCount', [address, 'pending']);
+    return parseInt(hex, 16);
+  }
+
+  /**
+   * Get balance for an address
+   * @param {string} address - Address as 0x-prefixed hex
+   * @returns {Promise<bigint>}
+   */
+  async get_balance(address) {
+    const hex = await this.request('eth_getBalance', [address, 'latest']);
+    return BigInt(hex);
+  }
+
+  /**
+   * Get code at an address
+   * @param {string} address - Address as 0x-prefixed hex
+   * @returns {Promise<string>}
+   */
+  async get_code(address) {
+    return this.request('eth_getCode', [address, 'latest']);
+  }
+
+  /**
+   * Call a contract (read-only)
+   * @param {object} call - Call object with to and data
+   * @returns {Promise<string>}
+   */
+  async call(call) {
+    return this.request('eth_call', [call, 'latest']);
+  }
+
+  /**
+   * Send a signed raw transaction
+   * @param {string} raw_transaction - Signed transaction as 0x-prefixed hex
+   * @returns {Promise<string>} Transaction hash
+   */
+  async send_raw_transaction(raw_transaction) {
+    return this.request('eth_sendRawTransaction', [raw_transaction]);
+  }
+
+  /**
+   * Get transaction receipt
+   * @param {string} tx_hash - Transaction hash
+   * @returns {Promise<object|null>}
+   */
+  async get_transaction_receipt(tx_hash) {
+    return this.request('eth_getTransactionReceipt', [tx_hash]);
+  }
+
+  /**
+   * Wait for transaction to be mined
+   * @param {string} tx_hash - Transaction hash
+   * @param {number} timeout_ms - Timeout in milliseconds
+   * @param {number} poll_interval_ms - Poll interval in milliseconds
+   * @returns {Promise<object>} Transaction receipt
+   */
+  async wait_for_receipt(tx_hash, timeout_ms = 60000, poll_interval_ms = 1000) {
+    const start = Date.now();
+
+    while (Date.now() - start < timeout_ms) {
+      const receipt = await this.get_transaction_receipt(tx_hash);
+      if (receipt) {
+        return receipt;
+      }
+      await new Promise(resolve => setTimeout(resolve, poll_interval_ms));
+    }
+
+    throw new Error(`Transaction ${tx_hash} timed out after ${timeout_ms}ms`);
+  }
+
+  /**
+   * Get ERC20 balance
+   * @param {string} token_address - Token contract address
+   * @param {string} owner_address - Owner address
+   * @returns {Promise<bigint>}
+   */
+  async get_erc20_balance(token_address, owner_address) {
+    // ERC20 balanceOf selector: 0x70a08231
+    const data = '0x70a08231' + padHex(owner_address, 32).slice(2);
+    const result = await this.call({ to: token_address, data });
+    return BigInt(result);
+  }
+}
+
+/**
+ * Create an RPC client
+ * @param {string} url - RPC URL
+ * @returns {RpcClient}
+ */
+export function create_rpc_client(url) {
+  return new RpcClient(url);
+}

package/src/transaction.js

@@ -0,0 +1,299 @@
+/**
+ * Transaction builder for Altius USD Multi-Token transactions (0x7a)
+ */
+
+import { keccak256, pad_hex, num_to_hex, rlp_encode } from './utils.js';
+
+/**
+ * Magic byte for fee payer signature (0x7B)
+ */
+const FEE_PAYER_SIGNATURE_MAGIC_BYTE = '0x7b';
+
+/**
+ * Build a USD Multi-Token transaction (0x7a type)
+ */
+export class TxBuilder {
+  constructor() {
+    this._chain_id = null;
+    this._nonce = null;
+    this._gas_limit = 21000;
+    this._to = null;
+    this._value = 0;
+    this._data = '0x';
+    this._max_priority_fee_per_gas = 0;
+    this._max_fee_per_gas = 0;
+    this._max_fee_per_gas_usd_attodollars = 0;
+    this._fee_token = null;
+    this._fee_payer = '0x0000000000000000000000000000000000000000';
+    this._fee_payer_signature = '0x';
+  }
+
+  /**
+   * Set chain ID
+   * @param {number} chain_id
+   * @returns {TxBuilder}
+   */
+  chain_id(chain_id) {
+    this._chain_id = chain_id;
+    return this;
+  }
+
+  /**
+   * Set nonce
+   * @param {number} nonce
+   * @returns {TxBuilder}
+   */
+  nonce(nonce) {
+    this._nonce = nonce;
+    return this;
+  }
+
+  /**
+   * Set gas limit
+   * @param {number} gas_limit
+   * @returns {TxBuilder}
+   */
+  gas_limit(gas_limit) {
+    this._gas_limit = gas_limit;
+    return this;
+  }
+
+  /**
+   * Set recipient
+   * @param {string} address - Address as 0x-prefixed hex
+   * @returns {TxBuilder}
+   */
+  to(address) {
+    this._to = address;
+    return this;
+  }
+
+  /**
+   * Set value (in wei)
+   * @param {BigInt|number} value
+   * @returns {TxBuilder}
+   */
+  value(value) {
+    this._value = BigInt(value);
+    return this;
+  }
+
+  /**
+   * Set input data (calldata)
+   * @param {string} data - Calldata as 0x-prefixed hex
+   * @returns {TxBuilder}
+   */
+  data(data) {
+    this._data = data;
+    return this;
+  }
+
+  /**
+   * Set max priority fee per gas (in wei)
+   * @param {BigInt|number} max_priority_fee_per_gas
+   * @returns {TxBuilder}
+   */
+  max_priority_fee_per_gas(max_priority_fee_per_gas) {
+    this._max_priority_fee_per_gas = BigInt(max_priority_fee_per_gas);
+    return this;
+  }
+
+  /**
+   * Set max fee per gas (in wei)
+   * @param {BigInt|number} max_fee_per_gas
+   * @returns {TxBuilder}
+   */
+  max_fee_per_gas(max_fee_per_gas) {
+    this._max_fee_per_gas = BigInt(max_fee_per_gas);
+    return this;
+  }
+
+  /**
+   * Set max fee per gas in USD attodollars
+   * @param {BigInt|number} max_fee_per_gas_usd_attodollars
+   * @returns {TxBuilder}
+   */
+  max_fee_per_gas_usd(max_fee_per_gas_usd_attodollars) {
+    this._max_fee_per_gas_usd_attodollars = BigInt(max_fee_per_gas_usd_attodollars);
+    return this;
+  }
+
+  /**
+   * Set fee token address
+   * @param {string} address - Fee token as 0x-prefixed hex
+   * @returns {TxBuilder}
+   */
+  fee_token(address) {
+    this._fee_token = address;
+    return this;
+  }
+
+  /**
+   * Set fee payer address (0-indexed for sender-pays)
+   * @param {string} address - Fee payer as 0x-prefixed hex
+   * @returns {TxBuilder}
+   */
+  fee_payer(address) {
+    this._fee_payer = address;
+    return this;
+  }
+
+  /**
+   * Set fee payer signature
+   * @param {string} signature - Signature as 0x-prefixed hex
+   * @returns {TxBuilder}
+   */
+  fee_payer_signature(signature) {
+    this._fee_payer_signature = signature;
+    return this;
+  }
+
+  /**
+   * Build the transaction object
+   * @returns {object}
+   */
+  build() {
+    if (!this._chain_id) throw new Error('chain_id is required');
+    if (this._nonce === null) throw new Error('nonce is required');
+    if (!this._fee_token) throw new Error('fee_token is required');
+
+    return {
+      chain_id: this._chain_id,
+      nonce: this._nonce,
+      gas_limit: this._gas_limit,
+      to: this._to || '0x0000000000000000000000000000000000000000',
+      value: this._value,
+      data: this._data,
+      max_priority_fee_per_gas: this._max_priority_fee_per_gas,
+      max_fee_per_gas: this._max_fee_per_gas,
+      max_fee_per_gas_usd_attodollars: this._max_fee_per_gas_usd_attodollars,
+      fee_token: this._fee_token,
+      fee_payer: this._fee_payer,
+      fee_payer_signature: this._fee_payer_signature,
+    };
+  }
+
+  /**
+   * Compute the sender signature hash for this transaction
+   * @returns {string}
+   */
+  signature_hash() {
+    const tx = this.build();
+
+    // For 0x7a transaction, the items are:
+    // [chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, accessList, feeToken, feePayer, maxFeePerGasUsdAttodollars, feePayerSignature]
+    const list = [
+      num_to_hex(tx.chain_id, 32),
+      num_to_hex(tx.nonce, 32),
+      num_to_hex(tx.max_priority_fee_per_gas, 32),
+      num_to_hex(tx.max_fee_per_gas, 32),
+      num_to_hex(tx.gas_limit, 32),
+      tx.to,
+      num_to_hex(tx.value, 32),
+      tx.data,
+      // Empty access list
+      '0xc0',
+      tx.fee_token,
+      tx.fee_payer,
+      num_to_hex(tx.max_fee_per_gas_usd_attodollars, 32),
+      tx.fee_payer_signature,
+    ];
+
+    const encoded = rlp_encode(list);
+    return keccak256(encoded);
+  }
+
+  /**
+   * Sign this transaction with a wallet
+   * @param {Wallet} wallet
+   * @returns {object} Signed transaction with raw transaction hex
+   */
+  async sign(wallet) {
+    const hash = this.signature_hash();
+    const sig = await wallet.sign_hash(hash);
+
+    // For 0x7a, we use y_parity (0 or 1) directly in the signature
+    const y_parity = sig.v;
+
+    const tx = this.build();
+
+    // Build signed transaction list (for EIP-2718 encoding)
+    const signed_fields = [
+      num_to_hex(tx.chain_id, 32),
+      num_to_hex(tx.nonce, 32),
+      num_to_hex(tx.max_priority_fee_per_gas, 32),
+      num_to_hex(tx.max_fee_per_gas, 32),
+      num_to_hex(tx.gas_limit, 32),
+      tx.to,
+      num_to_hex(tx.value, 32),
+      tx.data,
+      '0xc0', // empty access list
+      tx.fee_token,
+      tx.fee_payer,
+      num_to_hex(tx.max_fee_per_gas_usd_attodollars, 32),
+      tx.fee_payer_signature,
+      // Signature: y_parity (1 byte), r (32 bytes), s (32 bytes)
+      num_to_hex(y_parity, 1),
+      sig.r,
+      sig.s,
+    ];
+
+    // EIP-2718: first byte is type (0x7a), then RLP encoded fields
+    const rlp_fields = rlp_encode(signed_fields);
+    const type_byte = '0x7a';
+    const raw_transaction = type_byte + rlp_fields.slice(2); // Remove 0x prefix from RLP output
+
+    const transaction_hash = keccak256(raw_transaction);
+
+    return {
+      ...tx,
+      v: y_parity,
+      r: sig.r,
+      s: sig.s,
+      raw_transaction,
+      transaction_hash,
+    };
+  }
+}
+
+/**
+ * Create a new transaction builder
+ * @returns {TxBuilder}
+ */
+export function create_transaction() {
+  return new TxBuilder();
+}
+
+/**
+ * Calculate the hash that fee_payer should sign.
+ *
+ * This binds the sponsorship to:
+ * - Specific chain (chain_id) - prevents replay across chains
+ * - Specific sender - only this sender can use the sponsorship
+ * - Specific fee token - prevents cross-token attacks
+ * - Specific fee parameters - bounds the maximum fee
+ *
+ * @param {object} tx - Transaction object with chain_id, nonce, gas_limit, fee_token, fee_payer, max_fee_per_gas_usd_attodollars
+ * @param {string} sender - Sender address as 0x-prefixed hex
+ * @returns {string} The 32-byte hash that the fee_payer should sign
+ */
+export function fee_payer_signature_hash(tx, sender) {
+  // RLP encode the fields as a list
+  // [chain_id, nonce, gas_limit, fee_token, fee_payer, max_fee_per_gas_usd_attodollars, sender]
+  const list = [
+    num_to_hex(tx.chain_id, 32),
+    num_to_hex(tx.nonce, 32),
+    num_to_hex(tx.gas_limit, 32),
+    tx.fee_token,
+    tx.fee_payer,
+    num_to_hex(tx.max_fee_per_gas_usd_attodollars, 32),
+    sender,
+  ];
+
+  const encoded = rlp_encode(list);
+
+  // Prepend magic byte 0x7B
+  const with_magic = FEE_PAYER_SIGNATURE_MAGIC_BYTE + encoded.slice(2);
+
+  return keccak256(with_magic);
+}

package/src/utils.js

@@ -0,0 +1,58 @@
+/**
+ * Utility functions for the SDK
+ */
+
+import sha3 from 'js-sha3';
+import RLP from 'rlp';
+
+/**
+ * Compute keccak256 hash
+ * @param {string|Buffer} data - Input data
+ * @returns {string} Hash as 0x-prefixed hex string
+ */
+export function keccak256(data) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data.slice(2), 'hex');
+  const hash = sha3.keccak_256(buf);
+  return '0x' + hash;
+}
+
+/**
+ * Pad a hex string to specified bytes
+ * @param {string} hex - Hex string (with or without 0x prefix)
+ * @param {number} bytes - Target byte length
+ * @returns {string} Padded hex string
+ */
+export function pad_hex(hex, bytes) {
+  const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+  return '0x' + clean.padStart(bytes * 2, '0');
+}
+
+/**
+ * Convert number to padded hex
+ * @param {number|BigInt} num - Number to convert
+ * @param {number} bytes - Target byte length
+ * @returns {string} Padded hex string
+ */
+export function num_to_hex(num, bytes = 32) {
+  const hex = num.toString(16);
+  return pad_hex('0x' + hex, bytes);
+}
+
+/**
+ * Simple RLP encoding (for 0x7a transactions)
+ * @param {Array} items - Array of items to encode
+ * @returns {string} RLP encoded data as 0x-prefixed hex
+ */
+export function rlp_encode(items) {
+  const encoded = RLP.encode(items);
+  return '0x' + Buffer.from(encoded).toString('hex');
+}
+
+/**
+ * Compute transaction hash from signed transaction
+ * @param {object} signed_tx - Signed transaction
+ * @returns {string} Transaction hash
+ */
+export function transaction_hash(signed_tx) {
+  return keccak256(signed_tx);
+}

package/src/wallet.js

@@ -0,0 +1,123 @@
+/**
+ * Wallet - Local private key management and transaction signing
+ *
+ * IMPORTANT: Private keys never leave this class. All signing happens locally.
+ */
+
+import * as secp256k1 from 'noble-secp256k1';
+import { keccak256 } from './utils.js';
+
+/**
+ * Generate a random private key
+ * @returns {string} Private key as 0x-prefixed hex string
+ */
+export function generate_private_key() {
+  const privateKey = secp256k1.utils.randomPrivateKey();
+  return '0x' + Buffer.from(privateKey).toString('hex');
+}
+
+/**
+ * Derive address from private key
+ * @param {string} private_key - Private key as 0x-prefixed hex string
+ * @returns {string} Address as 0x-prefixed hex string
+ */
+export function private_key_to_address(private_key) {
+  const pk = private_key.slice(2);
+  const publicKey = secp256k1.getPublicKey(pk, true);
+  // Remove first byte (prefix) and take last 64 bytes (x, y)
+  const hash = keccak256(publicKey.slice(1));
+  // Take last 20 bytes
+  return '0x' + hash.slice(-40);
+}
+
+/**
+ * Parse DER signature to r, s components
+ * @param {string} der - DER encoded signature (hex string)
+ * @returns {{r: string, s: string}}
+ */
+function parse_der(der) {
+  // DER format: 30 [totalLen] 02 [rLen] [r] 02 [sLen] [s]
+  // der is a hex string (without 0x prefix)
+  let offset = 0;
+
+  // Skip 0x30
+  if (der.slice(offset, offset + 2) !== '30') throw new Error('Invalid DER: ' + der.slice(0, 10));
+  offset += 2;
+
+  // Skip total length
+  offset += 2;
+
+  // Check 0x02 (r)
+  if (der.slice(offset, offset + 2) !== '02') throw new Error('Invalid DER: expected 02');
+  offset += 2;
+
+  // Get r length
+  const rLen = parseInt(der.slice(offset, offset + 2), 16);
+  offset += 2;
+
+  // Get r (may need padding for leading zeros)
+  const rHex = der.slice(offset, offset + rLen * 2);
+  const r = '0x' + rHex.padStart(64, '0');
+  offset += rLen * 2;
+
+  // Check 0x02 (s)
+  if (der.slice(offset, offset + 2) !== '02') throw new Error('Invalid DER: expected 02');
+  offset += 2;
+
+  // Get s length
+  const sLen = parseInt(der.slice(offset, offset + 2), 16);
+  offset += 2;
+
+  // Get s
+  const sHex = der.slice(offset, offset + sLen * 2);
+  const s = '0x' + sHex.padStart(64, '0');
+
+  return { r, s };
+}
+
+/**
+ * Sign a transaction hash with private key
+ * @param {string} hash - Transaction hash as 0x-prefixed hex
+ * @param {string} private_key - Private key as 0x-prefixed hex
+ * @returns {{r: string, s: string, v: number}} Signature components
+ */
+export async function sign_hash(hash, private_key) {
+  const pk = private_key.slice(2);
+  const [derSig, recovery] = await secp256k1.sign(hash.slice(2), pk, { canonical: true, recovered: true });
+  const { r, s } = parse_der(derSig);
+  return { r, s, v: recovery };
+}
+
+/**
+ * Wallet class for local transaction signing
+ */
+export class Wallet {
+  /**
+   * Create a wallet from an existing private key
+   * @param {string} private_key - Private key as 0x-prefixed hex string
+   */
+  constructor(private_key) {
+    if (!private_key.startsWith('0x') || private_key.length !== 66) {
+      throw new Error('Invalid private key format');
+    }
+    this.private_key = private_key;
+    this.address = private_key_to_address(private_key);
+  }
+
+  /**
+   * Generate a new random wallet
+   * @returns {Wallet}
+   */
+  static generate() {
+    return new Wallet(generate_private_key());
+  }
+
+  /**
+   * Sign a transaction hash
+   * @param {string} hash - Transaction hash as 0x-prefixed hex
+   * @returns {{r: string, s: string, v: number}} Signature
+   */
+  async sign_hash(hash) {
+    return sign_hash(hash, this.private_key);
+  }
+}