@altiuslabs/tx-sdk 0.1.20 → 0.1.22

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.20",
+  "version": "0.1.22",
   "description": "SDK for signing and sending Altius USD multi-token transactions",
   "type": "module",
   "main": "src/index.js",

package/src/transaction.js

@@ -23,7 +23,7 @@ export class TxBuilder {
     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._max_fee_per_gas_usd_attodollars = 40000000000n; // $0.04/gas default
     this._fee_token = null;
     this._fee_payer = '0x0000000000000000000000000000000000000000';
     this._fee_payer_signature = '0x';
@@ -227,9 +227,14 @@ export class TxBuilder {
     const rBuffer = Buffer.from(sig.r.slice(2), 'hex');
     const sBuffer = Buffer.from(sig.s.slice(2), 'hex');
 
+    // Note: y_parity is used directly as a number in signature_bytes below
+
     // Build signed transaction list (for EIP-2718 encoding)
     // Format matches node's rlp_encode_fields: [chainId, nonce, ..., feePayerSignature, signature]
     // IMPORTANT: Use Buffer for addresses and data to match Rust alloy-rlp encoding
+    //
+    // NOTE: For signature encoding, we use RLP encoding to match Rust alloy's behavior.
+    // The signature (y_parity, r, s) is added to the RLP list and encoded together.
     const signed_fields = [
       BigInt(tx.chain_id),
       BigInt(tx.nonce),
@@ -244,14 +249,15 @@ export class TxBuilder {
       Buffer.from(feePayer.slice(2), 'hex'),  // fee_payer as buffer
       BigInt(tx.max_fee_per_gas_usd_attodollars),
       Buffer.from(tx.fee_payer_signature?.slice(2) || '', 'hex') || Buffer.alloc(0),
-      // Signature: y_parity (1 byte), r (32 bytes), s (32 bytes)
-      y_parity,
-      rBuffer,
-      sBuffer,
+      // Signature: y_parity, r, s - RLP encoded as part of the list
+      BigInt(y_parity),
+      Buffer.from(sig.r.slice(2), 'hex'),  // r as 32-byte buffer
+      Buffer.from(sig.s.slice(2), 'hex'),  // s as 32-byte buffer
     ];
 
     // EIP-2718: first byte is type (0x7a), then RLP encoded fields
     const rlp_fields_buf = RLP.encode(signed_fields);
+
     const raw_transaction = '0x7a' + rlp_fields_buf.toString('hex');
 
     const transaction_hash = keccak256(raw_transaction);

package/src/wallet.js

@@ -23,9 +23,12 @@ export function generate_private_key() {
  */
 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));
+  // false = uncompressed key (65 bytes starting with 0x04)
+  const publicKey = secp256k1.getPublicKey(pk, false);
+  // Convert hex string to Buffer
+  const publicKeyBuffer = Buffer.from(publicKey, 'hex');
+  // Remove first byte (prefix 0x04 for uncompressed key) and hash
+  const hash = keccak256(publicKeyBuffer.slice(1));
   // Take last 20 bytes
   return '0x' + hash.slice(-40);
 }
@@ -56,7 +59,13 @@ function parse_der(der) {
   offset += 2;
 
   // Get r (may need padding for leading zeros)
-  const rHex = der.slice(offset, offset + rLen * 2);
+  // DER uses signed integers, so if MSB >= 0x80, a 0x00 prefix is added
+  // We need to strip that prefix if present, then pad to 32 bytes
+  let rHex = der.slice(offset, offset + rLen * 2);
+  if (rHex.startsWith('00') && rLen === 33) {
+    // Strip the leading 0x00 added by DER encoding
+    rHex = rHex.slice(2);
+  }
   const r = '0x' + rHex.padStart(64, '0');
   offset += rLen * 2;
 
@@ -68,8 +77,12 @@ function parse_der(der) {
   const sLen = parseInt(der.slice(offset, offset + 2), 16);
   offset += 2;
 
-  // Get s
-  const sHex = der.slice(offset, offset + sLen * 2);
+  // Get s (may need to strip leading 0x00 added by DER encoding)
+  let sHex = der.slice(offset, offset + sLen * 2);
+  if (sHex.startsWith('00') && sLen === 33) {
+    // Strip the leading 0x00 added by DER encoding
+    sHex = sHex.slice(2);
+  }
   const s = '0x' + sHex.padStart(64, '0');
 
   return { r, s };