altius-tx-sdk 0.1.24

SDK for signing and sending Altius USD multi-token transactions
Documentation

Altius Transaction SDK (Rust)

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

Installation

Add to your Cargo.toml:

[dependencies]
altius-tx-sdk = "0.1"

Usage

Quick Start

use altius_tx_sdk::{TxClient, generate_private_key, USDA_ADDRESS};

let private_key = generate_private_key();
let client = TxClient::new(&private_key, "https://rpc.altius.xyz", USDA_ADDRESS)?;

let tx_hash = client.transfer_usda(recipient, 1_000_000).await?; // 1 USD
println!("Transaction hash: {}", tx_hash);

Transaction Builder

use altius_tx_sdk::{TxBuilder, TxFields};

let tx = TxBuilder::new()
    .chain_id(1)
    .nonce(0)
    .gas_limit(21000)
    .to(Some(address))
    .value(U256::ZERO)
    .fee_token(USDA_ADDRESS)
    .max_fee_per_gas_usd(50000000000)
    .build();

API Reference

Wallet & Signing

generate_private_key() -> String

Generate a new random private key.

let private_key = generate_private_key();

private_key_to_address(private_key: &str) -> Result<String>

Derive address from private key.

let address = private_key_to_address("0x...")?;

Wallet

Wallet struct for transaction signing.

use altius_tx_sdk::Wallet;

// Generate new wallet
let wallet = Wallet::generate()?;

// Create from private key
let wallet = Wallet::from_private_key("0x...")?;

Transaction Builder

TxBuilder

Builder for USD Multi-Token transactions.

use altius_tx_sdk::TxBuilder;
use alloy_primitives::{address, U256};

let tx = TxBuilder::new()
    .chain_id(1)
    .nonce(0)
    .gas_limit(21000)
    .to(Some(address!("0x...")))
    .value(U256::ZERO)
    .fee_token(USDA_ADDRESS)
    .max_fee_per_gas_usd(50000000000)
    .build();

TxBuilder Methods

Method Description
.chain_id(id: u64) Set chain ID
.nonce(nonce: u64) Set transaction nonce
.gas_limit(limit: u64) Set gas limit
.to(address: Option<Address>) Set recipient address
.to_address(address: Address) Set recipient address
.value(value: U256) Set transaction value
.data(data: Bytes) Set input data
.max_priority_fee_per_gas(gas: u128) Set max priority fee
.max_fee_per_gas(gas: u128) Set max fee per gas
.fee_token(address: Address) Set fee token address
.fee_payer(address: Option<Address>) Set fee payer (optional)
.max_fee_per_gas_usd(usd: u128) Set max fee in USD attodollars
.fee_payer_signature(signature: Bytes) Set fee payer signature
.erc20_transfer(token: Address, to: Address, amount: U256) Build ERC20 transfer
.build() -> TxFields Build transaction
.signature_hash() -> B256 Compute signature hash
.sign(signer: &impl Signer) -> Result<SignedTx> Sign transaction

RPC Client

RpcClient

JSON-RPC client for Altius node.

use altius_tx_sdk::RpcClient;

let rpc = RpcClient::new("https://rpc.altius.xyz");

RpcClient Methods

Method Description
.new(url: &str) -> Self Create RPC client
.get_chain_id() -> Result<u64> Get chain ID
.get_block_number() -> Result<u64> Get latest block
.get_balance(address: Address) -> Result<U256> Get native balance
.get_nonce(address: Address) -> Result<u64> Get transaction count
.get_code(address: Address) -> Result<Bytes> Get contract code
.call(call: CallRequest) -> Result<Bytes> Execute contract call
.send_raw_transaction(tx: Bytes) -> Result<B256> Send signed transaction
.get_transaction_receipt(hash: B256) -> Result<Option<TransactionReceipt>> Get receipt
.wait_for_receipt(hash: B256, timeout_ms: u64) -> Result<TransactionReceipt> Wait for receipt
.get_erc20_balance(token: Address, owner: Address) -> Result<U256> Get ERC20 balance

Nonce Manager

NonceManager

Manages transaction nonces with caching.

use altius_tx_sdk::{NonceManager, RpcClient};
use std::sync::Arc;

let rpc = Arc::new(RpcClient::new("https://rpc.altius.xyz"));
let nm = NonceManager::new(rpc, address);

NonceManager Methods

Method Description
.new(rpc: Arc<RpcClient>, address: Address) -> Self Create nonce manager
.get_nonce() -> Result<u64> Get current nonce
.get_and_increment_nonce() -> Result<u64> Get and increment nonce
.reset_nonce() Reset nonce cache

High-Level Client

TxClient

High-level transaction client.

use altius_tx_sdk::TxClient;

let client = TxClient::new(private_key, "https://rpc.altius.xyz", USDA_ADDRESS)?;

TxClientBuilder

use altius_tx_sdk::TxClientBuilder;

let client = TxClientBuilder::new(private_key, "https://rpc.altius.xyz")
    .fee_token(USDA_ADDRESS)
    .base_fee(50000000000)
    .gas_limit(100000)
    .build()?;

TxClient Methods

Method Description
.new(private_key: &str, rpc_url: &str, fee_token: &str) -> Result<Self> Create client
.address() -> Address Get wallet address
.chain_id() -> Result<u64> Get chain ID
.get_nonce() -> Result<u64> Get current nonce
.build_erc20_transfer(token: Address, recipient: Address, amount: U256) -> Result<TxBuilder> Build ERC20 transfer
.sign(tx: TxBuilder) -> Result<SignedTransaction> Sign transaction
.send(signed: SignedTransaction) -> Result<String> Send transaction
.send_and_wait(signed: SignedTransaction, timeout_ms: u64) -> Result<TransactionReceipt> Send and wait
.send_erc20_transfer(token: Address, recipient: Address, amount: U256) -> Result<String> Send ERC20 transfer
.transfer_usda(recipient: Address, amount_micro: u64) -> Result<String> Transfer USDA
.fee_token_balance(address: Address) -> Result<U256> Get fee token balance
.native_balance(address: Address) -> Result<U256> Get native balance
.reset_nonce() Reset nonce cache

Utilities

compute_fee_token_address(creator: Address, salt: B256) -> (Address, u64)

Compute deterministic fee token address.

use altius_tx_sdk::compute_fee_token_address;

let (address, index) = compute_fee_token_address(creator, salt);

is_reserved_address(creator: Address, salt: B256) -> bool

Check if address is reserved (index < 256).

use altius_tx_sdk::is_reserved_address;

let is_reserved = is_reserved_address(creator, salt);

is_fee_token_prefix(addr: Address) -> bool

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

use altius_tx_sdk::is_fee_token_prefix;

let has_prefix = is_fee_token_prefix(address);

is_valid_fee_token_address(addr: Address) -> bool

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

use altius_tx_sdk::is_valid_fee_token_address;

let is_valid = is_valid_fee_token_address(address);

is_index_reserved(index: u64) -> bool

Check if index is reserved (index < 256).

use altius_tx_sdk::is_index_reserved;

let is_reserved = is_index_reserved(100);

pad_hex(hex: &str, bytes: usize) -> String

Pad hex string to specified length.

use altius_tx_sdk::pad_hex;

let padded = pad_hex("0x1234", 32);

num_to_hex(num: u64, bytes: usize) -> String

Convert number to padded hex.

use altius_tx_sdk::num_to_hex;

let hex = num_to_hex(123, 32);

Constants

Constant Type Description
USDA_ADDRESS Address USDA Fee Token: 0xa1700000000000000000000000000000000000001
FEE_TOKEN_FACTORY_ADDRESS Address Fee Token Factory: 0xa170000000000000000000000000000000000000
FEE_MANAGER_ADDRESS Address Fee Manager: 0xFE00000000000000000000000000000000000001
ZERO_ADDRESS Address Zero address: 0x0000000000000000000000000000000000000000
BASE_FEE_ATTO u64 Base fee: 50,000,000,000
DEFAULT_MAX_FEE_PER_GAS u64 Default max fee: 100,000,000,000
DEFAULT_GAS_LIMIT u64 Default gas limit: 100,000
FAUCET_AMOUNT_MICRO u64 Faucet amount: 100,000,000
FAUCET_AMOUNT_WEI u128 Faucet amount: 100,000,000,000,000,000,000
DEFAULT_FAUCET_AMOUNT u128 Default faucet amount: 100,000,000,000,000,000,000
DEFAULT_FAUCET_AMOUNT_MICRO u64 Default faucet: 100,000,000
TRANSFER_AMOUNT_MICRO u64 Transfer amount: 10,000,000
TRANSFER_AMOUNT_WEI u128 Transfer amount: 10,000,000,000,000,000,000
RESERVED_THRESHOLD u64 Reserved threshold: 256
FAUCET_FEE_TOKEN Address Default faucet fee token

Security Note

IMPORTANT: Never transmit private keys over the network. Sign transactions locally and only send the signed raw transaction to the RPC node.

// WRONG - never send private key to server
// client.send_private_key_to_server(private_key).await;

// CORRECT - sign locally, send raw transaction
let signed = client.sign(tx).await?;
rpc.send_raw_transaction(signed.raw_transaction()).await?;

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

Key Addresses

Contract Address
USDA (Fee Token) 0xa1700000000000000000000000000000000000001
Fee Token Factory 0xa170000000000000000000000000000000000000
Fee Manager 0xFE00000000000000000000000000000000000001

License

MIT OR Apache-2.0