@altiuslabs/tx-sdk 0.1.19 → 0.1.21

package/README.md

@@ -14,7 +14,7 @@ npm install @altiuslabs/tx-sdk
 
 ```javascript
 import { TxClient, generate_private_key } from '@altiuslabs/tx-sdk';
-import { USDA_ADDRESS } from '@altius/tx-sdk/constants';
+import { USDA_ADDRESS } from '@altiuslabs/tx-sdk';
 
 // Generate a new wallet
 const privateKey = generate_private_key();
@@ -56,28 +56,278 @@ const { tx_hash } = await client.send_erc20_transfer(
 const receipt = await client.send_and_wait(tx, 60000);
 ```
 
+---
+
 ## API Reference
 
-### Core Classes
+### Wallet & Signing
 
-- **TxClient** - High-level client for sending transactions
-- **Wallet** - Key management and address derivation
-- **RpcClient** - JSON-RPC interaction
-- **NonceManager** - Nonce management
-- **TxBuilder** - Transaction building
+#### `generate_private_key() => string`
+Generate a new random private key.
 
-### Constants
+```javascript
+const privateKey = generate_private_key();
+```
+
+#### `private_key_to_address(privateKey: string) => string`
+Derive address from private key.
+
+```javascript
+const address = private_key_to_address('0x...');
+```
+
+#### `Wallet`
+Wallet class for local transaction signing.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
 
 ```javascript
-import {
-  USDA_ADDRESS,
-  FEE_TOKEN_FACTORY_ADDRESS,
-  FEE_MANAGER_ADDRESS,
-  BASE_FEE_ATTO,
-  DEFAULT_GAS_LIMIT,
-} from '@altiuslabs/tx-sdk/constants';
+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.
+
+```javascript
+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`
+
+```javascript
+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.
+
+```javascript
+import { keccak256 } from '@altiuslabs/tx-sdk';
+
+const hash = keccak256('0x...');
+```
+
+#### `pad_hex(hex: string, bytes: number) => string`
+Pad hex string to specified length.
+
+```javascript
+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.
+
+```javascript
+import { num_to_hex } from '@altiuslabs/tx-sdk';
+
+num_to_hex(123, 32); // '0x000000000000000000000000000000000000000000000000000000000000007b'
+```
+
+#### `rlp_encode(items: array) => string`
+RLP encode an array.
+
+```javascript
+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.
+
+```javascript
+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...).
+
+```javascript
+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).
+
+```javascript
+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).
+
+```javascript
+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.
@@ -91,6 +341,8 @@ 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):
@@ -99,6 +351,8 @@ This SDK supports the USD Multi-Token fee model (0x7a transaction type):
 - **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

@@ -1,6 +1,6 @@
 {
   "name": "@altiuslabs/tx-sdk",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "SDK for signing and sending Altius USD multi-token transactions",
   "type": "module",
   "main": "src/index.js",

package/src/constants.js

@@ -32,15 +32,10 @@ export const FEE_TOKEN_FACTORY_ADDRESS = '0xa17000000000000000000000000000000000
 
 /**
  * Fee Manager (Independent prefix)
- * Address: 0xFE0000000000000000000000000000000000000001
+ * Address: 0xFE00000000000000000000000000000000000001
  */
 export const FEE_MANAGER_ADDRESS = '0xFE00000000000000000000000000000000000001';
 
-/**
- * Fee token prefix (10 bytes) for validation
- */
-export const FEE_TOKEN_PREFIX = '0xa1700000';
-
 /**
  * Zero address
  */
@@ -87,6 +82,16 @@ export const FAUCET_AMOUNT_MICRO = BigInt(100_000_000);
  */
 export const FAUCET_AMOUNT_WEI = BigInt(100_000_000_000_000_000_000);
 
+/**
+ * Default faucet amount in token units (100 USDA with 18 decimals)
+ */
+export const DEFAULT_FAUCET_AMOUNT = BigInt(100_000_000_000_000_000_000);
+
+/**
+ * Default faucet amount in microdollars
+ */
+export const DEFAULT_FAUCET_AMOUNT_MICRO = 100_000_000;
+
 /**
  * Default transfer amount in microdollars (10 USDA)
  */

package/src/index.js

@@ -26,7 +26,7 @@ export { NonceManager, create_nonce_manager } from './nonce.js';
 export { TxClient, TxClientBuilder, create_tx_client } from './client.js';
 
 // Utilities
-export { keccak256, pad_hex, num_to_hex, rlp_encode, transaction_hash, computeFeeTokenAddress, isReservedAddress } from './utils.js';
+export { keccak256, pad_hex, num_to_hex, rlp_encode, transaction_hash, computeFeeTokenAddress, isReservedAddress, is_fee_token_prefix, is_valid_fee_token_address, is_index_reserved } from './utils.js';
 
 // Constants
 export * from './constants.js';

package/src/utils.js

@@ -117,3 +117,31 @@ export function isReservedAddress(address, creator, salt) {
   const { index } = computeFeeTokenAddress(creator, salt);
   return index < 256n;
 }
+
+/**
+ * Check if address has fee token prefix (0xa170...)
+ * @param {string} address - Address to check
+ * @returns {boolean} True if has fee token prefix
+ */
+export function is_fee_token_prefix(address) {
+  const clean = address.startsWith('0x') ? address.slice(2) : address;
+  return clean.startsWith('a170');
+}
+
+/**
+ * Check if address is valid fee token (has prefix and not zero)
+ * @param {string} address - Address to check
+ * @returns {boolean} True if valid fee token address
+ */
+export function is_valid_fee_token_address(address) {
+  return is_fee_token_prefix(address) && address !== '0x0000000000000000000000000000000000000000';
+}
+
+/**
+ * Check if index is reserved (index < 256)
+ * @param {bigint|number} index - Index to check
+ * @returns {boolean} True if reserved
+ */
+export function is_index_reserved(index) {
+  return BigInt(index) < 256n;
+}