@asentum/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,19 +1,68 @@
-import { Dilithium3Keypair } from '@asentum/crypto';
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface TransportOptions {
+    /** fetch implementation. Default: globalThis.fetch. */
+    fetch?: FetchLike;
+    /** Retries after the first attempt for 429 / 5xx / network errors. Default 3. */
+    retries?: number;
+    /** Per-request timeout in ms. Default 30,000 (the gateway gives up at 30 s too). */
+    requestTimeoutMs?: number;
+    /** First backoff delay in ms. Default 500. */
+    backoffBaseMs?: number;
+    /** Maximum backoff delay in ms. Default 10,000. */
+    backoffMaxMs?: number;
+    /** Extra headers on every request (for example Authorization for a private RPC). */
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST';
+    body?: unknown;
+    signal?: AbortSignal;
+    /** Override the transport's retry count for this request. */
+    retries?: number;
+    /** Retry on 5xx and network errors (default true). Set false for non-idempotent posts. */
+    retryOnServerError?: boolean;
+    /** Statuses that return their body instead of throwing (for example 404 on /dev/faucet). */
+    allowStatus?: number[];
+}
+interface HttpResult<T> {
+    status: number;
+    body: T;
+    headers: Headers;
+}
+declare class Transport {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly retries;
+    private readonly timeoutMs;
+    private readonly baseMs;
+    private readonly maxMs;
+    private readonly headers;
+    constructor(baseUrl: string, opts?: TransportOptions);
+    backoffDelay(attempt: number, retryAfterMs?: number): number;
+    request<T>(path: string, opts?: RequestOptions): Promise<HttpResult<T>>;
+}
 
 /**
- * AsentumClient — read-only interface to an Asentum node's RPC.
+ * Response types, matching node 0.8.1.
  *
- * Wraps the node's HTTP endpoints in a typed, Promise-based API.
- * No private keys, no signing — just reads. For sending transactions,
- * use {@link AsentumWallet} which extends the client with a keypair.
+ * Conventions (same as the node): heights, balances, nonces and gas are
+ * decimal STRINGS so big values survive JSON; amounts are wei (1 ASE =
+ * 10^18 wei); timestamps are Unix milliseconds; hashes are 0x hex.
  *
- * Works in Node.js (20+) and browsers — only depends on `fetch`.
+ * Addresses: every address field the SDK returns is ase1, also where the
+ * node itself answers with 0x hex (receipts, /participation, /v3/committee,
+ * governance proposers, JSON-RPC to/contractAddress). Hashes, raw bytes,
+ * and the contents of contract return values and event data are left
+ * exactly as the node sent them, so an address inside event data stays
+ * 0x hex (use toAse1 on it if you show it).
  */
-interface ChainInfo {
-    chainId: string;
-    height: number;
-    mempoolSize: number;
-    latestHeader: BlockHeader;
+/** "tip" = newest block on the best chain; "finalized" = can never change. */
+type BlockTag = 'tip' | 'latest' | 'pending' | 'finalized' | 'safe';
+interface Heads {
+    /** Finalized height. A block at or below it can never change. */
+    finalized: number;
+    /** Newest block on the best chain. Usually 2 to 4 blocks ahead of finalized. */
+    tip: number;
 }
 interface BlockHeader {
     parentHash: string;
@@ -21,17 +70,23 @@ interface BlockHeader {
     transactionsRoot: string;
     receiptsRoot: string;
     number: string;
+    /** Unix time in milliseconds. */
     timestamp: string;
     gasLimit: string;
     gasUsed: string;
     baseFeePerGas: string;
+    /** ase1. */
     proposer: string;
+    lastCommitBitmap?: string;
 }
-interface Block {
-    header: BlockHeader;
-    hash?: string;
-    transactions: Transaction[];
-    receipts: Receipt[];
+interface ChainInfo {
+    chainId: string;
+    /** FINALIZED height (not the tip). Use getHeads() for both. */
+    height: number;
+    /** This node's own mempool size. */
+    mempoolSize: number;
+    /** Header of the finalized head. There is no block hash in it. */
+    latestHeader: BlockHeader;
 }
 interface Transaction {
     kind: 'transfer' | 'deploy' | 'call';
@@ -41,60 +96,252 @@ interface Transaction {
         maxPriorityFeePerGas: string;
         maxFeePerGas: string;
         gasLimit: string;
+        /** ase1. A deploy goes to the zero address. */
         to: string;
         value: string;
         dataSize: number;
     };
+    /** Decoded method and args for calls. */
     call?: {
         method: string;
         args: unknown[];
     };
+    publicKeyLength?: number;
+    signatureLength?: number;
+    /** Key-less (key-once) transactions name their sender instead of carrying the public key. */
+    keyless?: boolean;
+    /** ase1. Only on key-less transactions. */
+    sender?: string;
+}
+interface ReceiptEvent {
+    name: string;
+    /** The event payload as the contract emitted it (usually an object). Addresses inside stay 0x hex. */
+    data: unknown;
 }
+/**
+ * GET /receipts/<hash>. The success flag is `success` (boolean). There is
+ * no `status` on this route; `status: "0x1"` belongs to the JSON-RPC receipt.
+ */
 interface Receipt {
     txHash: string;
     blockNumber: string;
     txIndex: number;
+    /** ase1 (the node sends 0x hex; the SDK converts). */
     sender: string;
+    /** ase1. For a deploy this is the new contract. */
     recipient: string;
-    kind: string;
+    kind: 'transfer' | 'deploy' | 'call' | string;
+    /** true: ran OK. false: ran and failed (see `error`). */
     success: boolean;
     gasUsed: string;
-    events: Array<{
-        name: string;
-        data: unknown;
-    }>;
+    events: ReceiptEvent[];
     returnValue?: unknown;
+    /** Only on a failed transaction: why it failed (for example a revert message). */
+    error?: string;
+    /**
+     * false: in a block on the best chain, not final yet (it can still move
+     * to another block, rarely). true: final, never changes. Absent only on
+     * receipts nested in block responses (use the block's own flag there).
+     */
+    finalized?: boolean;
+    /** Tip height minus blockNumber, plus 1 (decimal string). */
+    confirmations?: string;
+    /** Hash of the block it is in. Compare between polls to spot a move. */
+    blockHash?: string;
+    /** Only while not final: id of the pending block it is in. */
+    auraHash?: string;
+}
+interface Block {
+    header: BlockHeader;
+    /** Not in the node's block JSON; present only when the SDK knows it. */
+    hash?: string;
+    transactions: Transaction[];
+    receipts: Receipt[];
+    /** true for a finalized block; false for a pending tip block (only with { tip: true }). */
+    finalized?: boolean;
+    /** Only on a tip block. */
+    confirmations?: string;
+    /** Only on a tip block. */
+    auraHash?: string;
+}
+interface BlockReceipts {
+    blockNumber: string;
+    receipts: Receipt[];
+    /**
+     * Absent when the node does not have the height (above finalized without
+     * { tip: true }, or below this node's history). Then `receipts` is empty
+     * even if the block was not.
+     */
+    finalized?: boolean;
+    confirmations?: string;
+    auraHash?: string;
+    /** SDK convenience: false when the node did not have the height (no `finalized` field). */
+    available: boolean;
 }
 interface Balance {
+    /** ase1. */
     address: string;
+    /** Wei, read at the tip. */
     balance: string;
+    /** Account nonce at the tip. */
     nonce: string;
+    /**
+     * Next usable nonce: `nonce` plus this sender's transactions queued in
+     * this node's mempool. Sign your next transaction with this.
+     */
+    pendingNonce?: string;
 }
-interface ValidatorInfo {
+interface AccountInfo {
+    /** ase1. */
     address: string;
-    stake: string;
-    bondedAt: string;
-    pubKeySize: number;
+    exists: boolean;
+    balance?: string;
+    nonce?: string;
+    /** BLAKE3 of the contract source; all zeros for an account without code. */
+    codeHash?: string;
+    storageRoot?: string;
+    height: string;
+}
+interface PublicKeyStatus {
+    /** ase1. */
+    address: string;
+    /** The chain has this account's public key on record. */
+    recorded: boolean;
+    keyHash: string | null;
+    keylessActive: boolean;
+    keylessFromBlock: string | null;
+    nextBlock: string;
+    /** A key-less (smaller) transaction from this account would be accepted now. */
+    canOmitKey: boolean;
 }
 interface ViewCallResult {
     ok: boolean;
     reason?: string;
+    /** Whatever the method returned. Many contracts return a JSON string; BigInts come back as decimal strings. */
     returnValue?: unknown;
     gasUsed?: string;
-    events?: Array<{
-        name: string;
-        data: unknown;
-    }>;
+    events?: ReceiptEvent[];
+    /** The block whose state was read. */
+    blockNumber?: string;
+    /** Whether that state is final. */
+    finalized?: boolean;
 }
 interface TxResult {
+    /**
+     * true: the node checked the transaction and put it in its mempool. It
+     * has NOT run and is NOT in a block yet; it can still fail or be dropped.
+     */
     accepted: boolean;
+    /** Why it was rejected (only when accepted is false). */
     reason?: string;
     txHash?: string;
 }
+interface BatchTxResult {
+    accepted: number;
+    rejected: number;
+    total: number;
+    /** Same order as the request. Each has the shape of POST /tx. */
+    results: TxResult[];
+}
+interface EpochInfo {
+    head: string;
+    current: string;
+    blocksPerEpoch: string;
+    entryWindowBlocks: string;
+    currentStart: string;
+    currentEnds: string;
+    currentWindowOpensAt: string;
+    nextWindowOpensAt: string;
+}
+type CommitteeState = 'signing' | 'waiting_epoch_entry' | 'dormant' | 'pending_bond' | 'tombstoned';
+interface ValidatorInfo {
+    /** ase1. */
+    address: string;
+    stake: string;
+    bondedAt: string;
+    status?: string;
+    activeAtBlock?: string;
+    pubKeySize: number;
+    broadcastUrl?: string;
+    /**
+     * signing means the validator has voted and is not dormant. It does not
+     * mean it holds one of this epoch's committee seats (see getCommittee).
+     */
+    committeeState?: CommitteeState | string;
+    consecutiveMisses?: number;
+    lastVotedHeight?: string;
+    nextCommitteeEntryAt?: string | null;
+}
+interface ValidatorsResponse {
+    count: number;
+    /** ase1. */
+    stakingContract?: string;
+    epoch?: EpochInfo;
+    validators: ValidatorInfo[];
+}
+interface ParticipationEntry {
+    /** ase1 (the node sends 0x hex). */
+    address: string;
+    stake: string;
+    signedBlocks: number;
+    participationRatio: number;
+    lastSignedBlock: string | null;
+    status: 'signing' | 'idle' | 'dormant' | string;
+}
+interface Participation {
+    head: string;
+    scannedFrom: string;
+    lookback: number;
+    totalValidators: number;
+    signing: number;
+    idle: number;
+    dormant: number;
+    recentWindow: number;
+    validators: ParticipationEntry[];
+}
+interface Committee {
+    epoch: string;
+    /** Whether the committee lottery chose this committee. */
+    lottery: boolean;
+    /** ase1, in canonical order (the order commit bitmaps use). */
+    committee: string[];
+    /** ase1. */
+    leaderBase: string[];
+}
+interface FinalizedStatus {
+    height: string;
+    finalized: boolean;
+    /** Aura hash of the block finalized at this height (only when finalized). */
+    auraHash?: string;
+}
+interface LivenessEntry {
+    /** ase1. */
+    address: string;
+    lastVotedHeight: string | null;
+    consecutiveMisses: number;
+    baked: boolean;
+}
+interface Liveness {
+    head: string;
+    livenessWindow: string;
+    maxConsecutiveMisses: number;
+    /** ase1. The core validators. */
+    baked: string[];
+    tracked: LivenessEntry[];
+    [extra: string]: unknown;
+}
+interface Tombstones {
+    count: number;
+    /** ase1. */
+    slashingContract: string;
+    tombstones: unknown[];
+}
 interface Metadata {
+    /** Hex, e.g. "0x58f". */
     chainId: string;
     chainName: string;
     chainIdDecimal: string;
+    /** Cached up to 30 s on the gateway, so it lags. */
     currentBlock: string;
     nativeCurrency: {
         name: string;
@@ -103,205 +350,761 @@ interface Metadata {
     };
     rpcUrls: string[];
     blockExplorerUrls: string[];
-    faucetUrl: string;
+    /** Not a public faucet. Test ASE comes from the airdrop dashboard. */
+    faucetUrl?: string;
 }
-declare class AsentumClient {
-    readonly rpcUrl: string;
-    constructor(rpcUrl: string);
-    /** Get chain info including the latest block header. */
-    getChainInfo(): Promise<ChainInfo>;
-    /** Get the current block height. */
-    getBlockNumber(): Promise<number>;
-    /** Get the chain ID as a bigint. */
-    getChainId(): Promise<bigint>;
-    /** Get a block by number, including transactions and receipts. */
-    getBlock(number: number | bigint): Promise<Block | null>;
-    /** Get the balance and nonce for an address. */
-    getBalance(address: string): Promise<Balance>;
-    /** Get the nonce for an address (shorthand for getBalance().nonce). */
-    getNonce(address: string): Promise<bigint>;
-    /** Get the receipt for a transaction by hash. */
-    getReceipt(txHash: string): Promise<Receipt | null>;
-    /** Get the source code of a deployed contract (hex-encoded). */
-    getCode(address: string): Promise<string>;
-    /** Get the source code of a deployed contract as a UTF-8 string. */
-    getContractSource(address: string): Promise<string | null>;
-    /** Call a contract view function (read-only, no transaction). */
-    viewCall(contract: string, method: string, args?: unknown[]): Promise<ViewCallResult>;
-    /** Get the current active validator set. */
-    getValidators(): Promise<{
-        count: number;
-        validators: ValidatorInfo[];
-    }>;
-    /** Get the chain metadata (EIP-3085 shape). */
-    getMetadata(): Promise<Metadata>;
-    /** Health check. */
-    isHealthy(): Promise<boolean>;
-    /** Readiness check (chain advancing). */
-    isReady(): Promise<boolean>;
-    /** Request test ASE from the faucet. */
-    faucet(to: string, amount?: string): Promise<TxResult>;
-    /** Submit a raw signed transaction (hex-encoded SSZ bytes). */
-    submitRawTx(rawTxHex: string): Promise<TxResult>;
-    /** Send a raw JSON-RPC request. */
-    jsonRpc<T>(method: string, params?: unknown[]): Promise<T>;
-    private get;
-    private post;
+interface ApiInfo {
+    name: string;
+    /** A fixed placeholder, not the node release. */
+    version: string;
+    chainId: string;
+    height: string;
+    /** ase1. */
+    faucetAddress?: string;
+}
+interface GovernanceProposal {
+    id: number;
+    title: string;
+    description: string;
+    category?: string;
+    /** ase1 (the contract stores 0x hex). */
+    proposer: string;
+    createdAt: string;
+    votingEndsAt: string;
+    votesFor: string;
+    votesAgainst: string;
+    totalVoteWeight: string;
+    status: string;
+    amendmentCount?: number;
+    libraryName?: string | null;
+    bond?: string;
+    bondReturned?: boolean;
+    bondForfeited?: boolean;
+    version?: number;
+    executedAt?: string | null;
+    [extra: string]: unknown;
+}
+interface GovernanceProposalDetail {
+    proposal: GovernanceProposal;
+    amendments: unknown[];
+}
+interface GovernanceLocked {
+    /** ase1. */
+    address: string;
+    /** Wei locked in votes. */
+    locked: string;
+}
+interface GovernanceWithdrawable {
+    /** ase1. */
+    address: string;
+    locked: string;
+    withdrawable: string;
+    positions: unknown[];
+    [extra: string]: unknown;
+}
+/** A decoded contract event from eth_getLogs (finalized blocks only). */
+interface Log {
+    /** ase1: the contract that emitted it. */
+    address: string;
+    /** topics[0]: BLAKE3 of the event name (not Keccak). */
+    topic: string;
+    topics: string[];
+    /** Event name when the SDK knows it (you filtered by name). */
+    eventName?: string;
+    /** JSON.parse of the UTF-8 data, or the raw text when it is not JSON. */
+    data: unknown;
+    /** Raw 0x hex data as the node sent it. */
+    rawData: string;
+    blockNumber: number;
+    blockHash: string;
+    transactionHash: string;
+    transactionIndex: number;
+    /** Counts across the whole block, so (blockHash, logIndex) is unique. */
+    logIndex: number;
+    removed: boolean;
+}
+interface LogFilter {
+    /** Contract address (ase1 or 0x), or several. */
+    address?: string | string[];
+    /** Event name; the SDK computes topics[0] = BLAKE3(name). */
+    event?: string;
+    /** Raw topics, if you already have them. Ignored when `event` is set. */
+    topics?: (string | string[] | null)[];
+    /** Height or "latest"/"finalized"/"earliest". Default "latest" (the finalized head). */
+    fromBlock?: number | bigint | string;
+    toBlock?: number | bigint | string;
+}
+/** Ethereum-shaped transaction from eth_getTransactionByHash, addresses as ase1. */
+interface EthTransaction {
+    hash: string;
+    blockHash: string | null;
+    blockNumber: string | null;
+    transactionIndex: string | null;
+    /** ase1. */
+    from: string;
+    /** ase1, null for a deploy. */
+    to: string | null;
+    nonce: string;
+    value: string;
+    gas: string;
+    gasPrice?: string;
+    input: string;
+    finalized?: boolean;
+    [extra: string]: unknown;
 }
 
+/** The public testnet gateway. */
+declare const DEFAULT_RPC = "https://testnet.asentum.com";
+/** Address of the governance contract (0x...0003), ase1. */
+declare const GOVERNANCE_CONTRACT: string;
+/** eth_getLogs scans at most this many blocks per call. */
+declare const MAX_LOG_RANGE = 10000;
+interface ClientOptions extends TransportOptions {
+}
+interface CallOptions {
+    signal?: AbortSignal;
+    /** Override the retry count for this call. */
+    retries?: number;
+}
+interface BlockOptions extends CallOptions {
+    /** Also answer heights above the finalized head, from the pending block on the node's best chain. Default false. */
+    tip?: boolean;
+}
+interface ReceiptOptions extends CallOptions {
+    /** Only return a receipt once its block is final (`?tip=0`). Default false: tip receipts too, flagged finalized: false. */
+    finalizedOnly?: boolean;
+}
+interface ViewOptions extends CallOptions {
+    /** "tip" (default; "latest"/"pending" mean the same) or "finalized" ("safe"). No historical reads. */
+    blockTag?: BlockTag;
+}
+type WaitUntil = 'included' | 'final';
 /**
- * AsentumContract — a deployed contract instance that wraps view calls
- * and write transactions.
- *
- * Usage:
- *
- *   // Deploy via a wallet
- *   const contract = await wallet.deploy(source);
- *   console.log(contract.address);
+ * Options for {@link AsentumClient.waitForReceipt} and `tx.wait()`.
  *
- *   // Or wrap an existing deployed contract
- *   const contract = new AsentumContract(client, '0xabc...');
- *
- *   // Read (free, no signature)
- *   const name = await contract.view('name');
- *   const balance = await contract.view('balanceOf', ['0x...']);
- *
- *   // Write (requires a wallet)
- *   const tx = await contract.send('transfer', ['0x...', '1000']);
- *   const receipt = await tx.wait();
+ * A transaction goes pending (accepted into a mempool) -> in a block
+ * (receipt with finalized: false, about one block after sending) -> final
+ * (finalized: true, a few blocks later). Rarely a block loses to a sibling
+ * at the same height before it is final: the receipt disappears and the
+ * transaction lands again in a later block. onReorg reports that.
  */
-
-declare class AsentumContract {
-    readonly client: AsentumClient;
-    readonly address: string;
-    /** The deploy tx, if this contract was deployed in this session. */
-    readonly deployTx?: SentTx;
-    /** The wallet used to deploy this contract, if any. Used as default signer for send(). */
-    private wallet?;
-    constructor(client: AsentumClient, address: string, deployTx?: SentTx, wallet?: AsentumWallet);
+interface WaitOptions {
+    /** Resolve at the first receipt ("included", default) or only once final ("final"). */
+    until?: WaitUntil;
+    /** Give up after this long. Default 60,000 for "included", 120,000 for "final". */
+    timeoutMs?: number;
+    /** Poll interval. Default 1,000 (blocks are about 2.5 s apart). */
+    pollIntervalMs?: number;
+    /** The transaction is in a block (show success now). Fires again after a reorg puts it in another block. */
+    onIncluded?: (receipt: Receipt) => void;
+    /** The block is final. Only fires with until: "final". */
+    onFinal?: (receipt: Receipt) => void;
+    /** A block the transaction was in lost to a sibling; `previous` is the receipt that is no longer valid. */
+    onReorg?: (previous: Receipt) => void;
+    /** Abort waiting (rejects with AbortError). The transaction itself is not affected. */
+    signal?: AbortSignal;
+    /** Reject with TxFailedError when the receipt has success: false. Default false (resolve with the receipt). */
+    throwOnFailure?: boolean;
+    /** In a browser, do not poll while the tab is hidden. Default true. */
+    pauseWhenHidden?: boolean;
+}
+/** topics[0] of an event: BLAKE3 of the UTF-8 event name, 0x hex. */
+declare function eventTopic(name: string): string;
+declare class AsentumClient {
+    readonly rpcUrl: string;
+    /** @internal */
+    readonly transport: Transport;
+    private chainIdCache?;
+    constructor(rpcUrl?: string, options?: ClientOptions);
+    /** Finalized height and tip in one small call (GET /v3/heads). */
+    getHeads(opts?: CallOptions): Promise<Heads>;
+    /** Newest block height on the best chain. */
+    getTipNumber(opts?: CallOptions): Promise<number>;
+    /** Finalized height (same as eth_blockNumber and getBlockNumber). */
+    getFinalizedNumber(opts?: CallOptions): Promise<number>;
+    /** Chain id, finalized height, this node's mempool size and the finalized header (GET /chain, cached 1 s on the gateway). */
+    getChainInfo(opts?: CallOptions): Promise<ChainInfo>;
+    /** The FINALIZED height. Use getTipNumber() for the newest block. */
+    getBlockNumber(opts?: CallOptions): Promise<number>;
+    /** Chain id (1423 on the public testnet). Cached after the first call. */
+    getChainId(opts?: CallOptions): Promise<bigint>;
+    /** Chain details in EIP-3085 shape (GET /metadata, cached 30 s on the gateway). */
+    getMetadata(opts?: CallOptions): Promise<Metadata>;
+    /** Node identity (GET /api). `version` is a fixed placeholder, not the node release. */
+    getApiInfo(opts?: CallOptions): Promise<ApiInfo>;
+    /** The genesis spec (GET /genesis, about 17 KB). Address fields converted to ase1. */
+    getGenesis(opts?: CallOptions): Promise<Record<string, unknown>>;
+    /** Liveness probe (GET /health). True as long as the HTTP server answers. Does not check sync. */
+    isHealthy(opts?: CallOptions): Promise<boolean>;
+    /**
+     * Readiness probe (GET /ready): true on 200 "ready", false on 503 "stale"
+     * or no answer. Caveat: node 0.8.1 compares seconds with milliseconds
+     * here, so it reports ready even on a stalled node. To detect a stall,
+     * check that getHeads() keeps moving.
+     */
+    isReady(opts?: CallOptions): Promise<boolean>;
+    /** Balance (wei), nonce and pendingNonce at the tip (GET /balance). */
+    getBalance(address: string, opts?: CallOptions): Promise<Balance>;
+    /**
+     * The nonce to SEND with. Default: the node's mempool-aware pendingNonce,
+     * so several sends in a row get n, n+1, n+2. `{ pending: false }` gives
+     * the account nonce at the tip.
+     */
+    getNonce(address: string, opts?: CallOptions & {
+        pending?: boolean;
+    }): Promise<bigint>;
+    /** Full account record: balance, nonce, codeHash, storageRoot (GET /asentum/account). */
+    getAccount(address: string, opts?: CallOptions): Promise<AccountInfo>;
+    /** Whether the chain has this account's public key on record, so it may send key-less transactions (GET /public-key). */
+    getPublicKeyStatus(address: string, opts?: CallOptions): Promise<PublicKeyStatus>;
     /**
-     * Call a view function (read-only, free, no transaction).
+     * A block with decoded transactions and receipts, or null when this node
+     * does not have it. Finalized blocks only, unless `{ tip: true }`.
+     * (0.1.x returned the node's error object here instead of null.)
+     */
+    getBlock(number: number | bigint, opts?: BlockOptions): Promise<Block | null>;
+    /** Only the receipts of a block (GET /block/<n>/receipts). Check `available` before trusting an empty list. */
+    getBlockReceipts(number: number | bigint, opts?: BlockOptions): Promise<BlockReceipts>;
+    /** The block as SSZ bytes (0x hex), or null. Note: also serves pending heights without saying so. */
+    getRawBlock(number: number | bigint, opts?: CallOptions): Promise<string | null>;
+    /** Whether a height is finalized on this node, and the Aura hash finalized there (GET /v3/finalized). */
+    getFinalizedStatus(height: number | bigint, opts?: CallOptions): Promise<FinalizedStatus>;
+    /**
+     * The receipt of a transaction, or null when it is not in a block (yet).
+     * Tip receipts are included by default (finalized: false); see
+     * `finalizedOnly`. Check `success`, not `status`.
      *
-     * @param method - The function name to call.
-     * @param args   - Arguments to pass to the function.
-     * @returns The return value of the function.
+     * Throws RpcError for a malformed hash and HttpError / NetworkError after
+     * retries (0.1.x returned null for every error).
+     */
+    getReceipt(txHash: string, opts?: ReceiptOptions): Promise<Receipt | null>;
+    /** The transaction body from eth_getTransactionByHash (in-block transactions only, tip too), or null. */
+    getTransaction(txHash: string, opts?: CallOptions): Promise<EthTransaction | null>;
+    /**
+     * Submit one signed transaction (POST /tx). Does not throw on rejection:
+     * check `accepted`. `accepted: true` only means "in this node's mempool".
      */
-    view(method: string, args?: unknown[]): Promise<unknown>;
+    submitRawTx(rawTxHex: string, opts?: CallOptions): Promise<TxResult>;
     /**
-     * Call a view function and return the full result including gas + events.
+     * Submit several signed transactions in one request (POST /tx/batch).
+     * They are admitted in order; one rejection does not stop the rest.
      */
-    viewFull(method: string, args?: unknown[]): Promise<ViewCallResult>;
+    submitRawTxBatch(rawTxs: string[], opts?: CallOptions): Promise<BatchTxResult>;
     /**
-     * Send a state-changing transaction to the contract.
+     * Wait for a transaction's receipt. Polls GET /receipts about once a
+     * second, backs off on 429 / 5xx, and follows the receipt through a
+     * reorg (onReorg, then onIncluded again for the new block).
      *
-     * @param method  - The function name to call.
-     * @param args    - Arguments to pass.
-     * @param opts    - Optional: value to attach, gas limit, nonce, wallet override.
-     * @returns A SentTx with `.hash` and `.wait()`.
+     * Resolves with the receipt (until: "included", the default) or with the
+     * final receipt (until: "final"). Rejects with TimeoutError (not a
+     * failure: the tx may still land), AbortError, or TxFailedError when
+     * throwOnFailure is set.
      */
-    send(method: string, args?: unknown[], opts?: {
-        value?: string | number | bigint;
-        gasLimit?: bigint;
-        nonce?: bigint;
-        wallet?: AsentumWallet;
-    }): Promise<SentTx>;
+    waitForReceipt(txHash: string, opts?: WaitOptions): Promise<Receipt>;
     /**
-     * Attach a wallet to this contract for future send() calls.
+     * Run a contract method read-only (POST /view). ase1 addresses inside
+     * `args` are converted to 0x hex first (the node does not convert them,
+     * and contracts store accounts as hex). Reads the tip unless
+     * `{ blockTag: 'finalized' }`. Does not throw on ok: false; see view().
      */
-    connect(wallet: AsentumWallet): AsentumContract;
+    viewCall(contract: string, method: string, args?: unknown[], opts?: ViewOptions): Promise<ViewCallResult>;
+    /** Like viewCall, but returns the method's return value and throws ViewError on ok: false. */
+    view<T = unknown>(contract: string, method: string, args?: unknown[], opts?: ViewOptions): Promise<T>;
+    /** A contract's source, hex-encoded UTF-8 (eth_getCode). "0x" for an account without code. */
+    getCode(address: string, opts?: CallOptions): Promise<string>;
+    /** A contract's JavaScript source as text, or null when the address has no code. */
+    getContractSource(address: string, opts?: CallOptions): Promise<string | null>;
+    /** A contract storage value by key (a plain string such as "self"), as text, or null when empty (eth_getStorageAt). */
+    getStorageAt(address: string, key: string, opts?: CallOptions): Promise<string | null>;
     /**
-     * Get the source code of this contract as a UTF-8 string.
-     * Returns null if the address has no deployed code.
+     * Contract events from eth_getLogs, decoded. Finalized blocks only. A
+     * range wider than 10,000 blocks is split into several calls.
+     *
+     *   await client.getLogs({ address: 'ase1...', event: 'Transfer', fromBlock: 570000, toBlock: 571000 })
      */
-    getSource(): Promise<string | null>;
+    getLogs(filter?: LogFilter, opts?: CallOptions): Promise<Log[]>;
+    /** Every bonded validator with stake and committee state, plus the epoch (GET /validators, about 260 KB). */
+    getValidators(opts?: CallOptions): Promise<ValidatorsResponse>;
+    /** Who signed recent blocks (GET /participation). lookback 1 to 10,000, default 1,000. */
+    getParticipation(opts?: CallOptions & {
+        lookback?: number;
+    }): Promise<Participation>;
+    /** The voting committee of an epoch (default: current), ase1, in canonical order (GET /v3/committee). */
+    getCommittee(opts?: CallOptions & {
+        epoch?: number | bigint;
+    }): Promise<Committee>;
+    /** The node's liveness tracker (GET /consensus/liveness, about 40 KB). */
+    getLiveness(opts?: CallOptions): Promise<Liveness>;
+    /** Slashed and tombstoned validators (GET /slashing/tombstones). */
+    getTombstones(opts?: CallOptions): Promise<Tombstones>;
+    /** The newest proposals, up to 50 (GET /governance/proposals). */
+    getProposals(opts?: CallOptions): Promise<GovernanceProposal[]>;
+    /** One proposal with its amendments, or null for an unknown id (GET /governance/proposal/<id>). */
+    getProposal(id: number | string, opts?: CallOptions): Promise<GovernanceProposalDetail | null>;
+    /** ASE (wei) an address has locked in governance votes (GET /governance/locked). */
+    getGovernanceLocked(address: string, opts?: CallOptions): Promise<GovernanceLocked>;
+    /** Vote weight still locked vs ready to withdraw (GET /governance/withdrawable). */
+    getGovernanceWithdrawable(address: string, opts?: CallOptions): Promise<GovernanceWithdrawable>;
+    /** Approved libraries (GET /governance/libraries). Library approval is disabled, so always empty today. */
+    getGovernanceLibraries(opts?: CallOptions): Promise<unknown[]>;
+    /** One approved library by name, or null (GET /governance/library/<name>). */
+    getGovernanceLibrary(name: string, opts?: CallOptions): Promise<unknown | null>;
     /**
-     * Get the ASE balance of this contract.
+     * @deprecated The node's POST /dev/faucet is OFF unless the operator sets
+     * ASENTUM_DEV_FAUCET=1, which only makes sense on a local devnet. Every
+     * public node answers `{ accepted: false, reason: "faucet not enabled on
+     * this node" }`. For test ASE use the airdrop dashboard (see the docs page
+     * "Get Test ASE"). Kept for local devnets; never throws on 404 / 429.
      */
-    getBalance(): Promise<bigint>;
+    faucet(to: string, amount?: string, opts?: CallOptions): Promise<TxResult>;
+    /** Send one Ethereum-style JSON-RPC request to POST /. Throws JsonRpcError on an error object. */
+    jsonRpc<T>(method: string, params?: unknown[], opts?: CallOptions): Promise<T>;
+    /** GET and return the body as is. */
+    protected get<T>(path: string, opts?: CallOptions & Pick<RequestOptions, 'allowStatus'>): Promise<T>;
+    /** GET and throw RpcError when the body carries an `error` field (the node's HTTP 200 errors). */
+    protected getChecked<T>(path: string, opts?: CallOptions & Pick<RequestOptions, 'allowStatus'>): Promise<T>;
+}
+
+interface ContractSendOpts {
+    /** ASE to send with the call, parsed with parseAse ("1.5" = 1.5 ASE, bigint = wei). Prefer valueWei. */
+    value?: string | number | bigint;
+    /** Value in wei. Takes precedence over `value`. */
+    valueWei?: bigint | string;
+    gasLimit?: bigint;
+    nonce?: bigint;
+    /** Signer for this call; default the wallet attached with connect() or deploy(). */
+    wallet?: AsentumWallet;
+    signal?: AbortSignal;
+}
+declare class AsentumContract {
+    readonly client: AsentumClient;
+    /** ase1. (0.1.x kept whatever was passed in; a deploy gave 0x hex.) */
+    readonly address: string;
+    /** Lowercase 0x hex, what other contracts and msg.sender comparisons use. */
+    readonly addressHex: string;
+    /** The deploy transaction, when this contract was deployed in this session. */
+    readonly deployTx?: SentTx;
+    private wallet?;
+    constructor(client: AsentumClient, address: string, deployTx?: SentTx, wallet?: AsentumWallet);
+    /** Call a view method (free, no transaction) and return its value. Throws ViewError on ok: false. */
+    view<T = unknown>(method: string, args?: unknown[], opts?: ViewOptions): Promise<T>;
+    /** Call a view method and return the full result: value, gas, events, blockNumber, finalized. */
+    viewFull(method: string, args?: unknown[], opts?: ViewOptions): Promise<ViewCallResult>;
+    /** Send a state-changing call. Needs a wallet (connect() or opts.wallet). */
+    send(method: string, args?: unknown[], opts?: ContractSendOpts): Promise<SentTx>;
+    /** A copy of this contract that signs with `wallet`. */
+    connect(wallet: AsentumWallet): AsentumContract;
+    /** The contract's JavaScript source, or null if the address has no code. */
+    getSource(opts?: CallOptions): Promise<string | null>;
+    /** The contract's ASE balance in wei. */
+    getBalance(opts?: CallOptions): Promise<bigint>;
+    /** The account record (codeHash = BLAKE3 of the source, storageRoot). */
+    getAccount(opts?: CallOptions): Promise<AccountInfo>;
     /**
-     * Wait for the deploy transaction to be confirmed (if this contract
-     * was deployed in this session). Useful after `wallet.deploy()`.
+     * Events this contract emitted, decoded (eth_getLogs, finalized blocks
+     * only, ranges over 10,000 blocks are split). `eventName` undefined = all.
      */
-    waitForDeploy(timeoutMs?: number): Promise<Receipt>;
+    getEvents(eventName?: string, range?: {
+        fromBlock?: number | bigint | string;
+        toBlock?: number | bigint | string;
+    }, opts?: CallOptions): Promise<Log[]>;
+    /**
+     * Wait for the deploy transaction (only when deployed in this session).
+     * Accepts a timeout in ms (0.1.x) or WaitOptions, e.g. { until: 'final' }.
+     */
+    waitForDeploy(timeoutOrOpts?: number | WaitOptions): Promise<Receipt>;
+}
+
+interface Dilithium3Keypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
 }
 
 /**
- * Parse an ASE amount string into wei (bigint).
- * Accepts: "1", "1.5", "0.001", or a raw wei integer string.
+ * Strict ASE to wei: the input is ALWAYS read as ASE.
+ * "1" -> 10^18, "0.5" -> 5 * 10^17, 2 -> 2 * 10^18. At most 18 decimals.
+ */
+declare function aseToWei(amount: string | number): bigint;
+/**
+ * Parse an amount into wei, the way 0.1.x did. Kept for compatibility; it
+ * has one trap, so prefer {@link aseToWei} (always ASE) or pass wei as a
+ * bigint:
+ *
+ *   - bigint: already wei, returned as is.
+ *   - number or decimal string ("1", "1.5"): ASE.
+ *   - an integer string with MORE than 18 digits: treated as wei.
+ *     ("1000000000000000000000" is 1,000 ASE in wei; "100" is 100 ASE.)
  */
 declare function parseAse(amount: string | number | bigint): bigint;
+/** Format wei as an ASE decimal string without trailing zeros: 1500000000000000000n -> "1.5". */
+declare function formatAse(wei: bigint | string | number): string;
+/** Wei from a bigint, a decimal integer string or a safe integer number. Throws on anything else. */
+declare function toWei(v: bigint | string | number): bigint;
+
 /**
- * Format a wei bigint as a human-readable ASE string.
+ * Format an address for display: ase1 by default. The env override
+ * `ASENTUM_ADDR_FORMAT=hex` returns lowercase 0x hex instead.
  */
-declare function formatAse(wei: bigint | string): string;
-interface SendTransferOpts {
-    /** Recipient address (0x-prefixed, 40 hex chars). */
-    to: string;
-    /** Amount in ASE (e.g. "1.5") or wei (bigint). */
-    amount: string | number | bigint;
-    /** Override the gas limit. Default: 21,000. */
-    gasLimit?: bigint;
-    /** Override the nonce. Default: auto-fetched from the chain. */
+declare function formatAddress(input: string | Uint8Array): string;
+/**
+ * Key-less transactions (key-once, live since block 528,000): once the chain
+ * has an account's public key on record, its transactions may name the
+ * sender instead of carrying the 1,952-byte key, which makes them about a
+ * third smaller.
+ *   "off"    always include the key (default, works for every account)
+ *   "auto"   go key-less once GET /public-key says canOmitKey
+ *   "always" always key-less (rejected if the key is not on record)
+ */
+type KeylessMode = 'off' | 'auto' | 'always';
+interface WalletOptions {
+    keyless?: KeylessMode;
+}
+interface CommonTxOpts {
+    /** Override the nonce. Default: allocated by the wallet (see getNonce / resetNonce). */
     nonce?: bigint;
+    /** Override the gas limit. */
+    gasLimit?: bigint;
+    /** Max fee per gas in wei. Default 1 (the base fee is 1 wei per gas). */
+    maxFeePerGas?: bigint;
+    /** Override the wallet's key-less mode for this transaction. */
+    keyless?: KeylessMode;
+    signal?: AbortSignal;
 }
-interface SendCallOpts {
-    /** Contract address (0x-prefixed, 40 hex chars). */
+interface SendTransferOpts extends CommonTxOpts {
+    /** Recipient, ase1 or 0x hex. */
     to: string;
-    /** Method name to call on the contract. */
+    /**
+     * Amount, parsed with parseAse: a number or decimal string is ASE
+     * ("1.5" = 1.5 ASE), a bigint is wei. Careful: an integer STRING longer
+     * than 18 digits is read as wei. Prefer `amountWei` for exact values.
+     */
+    amount?: string | number | bigint;
+    /** Amount in wei (bigint or decimal integer string). Takes precedence over `amount`. */
+    amountWei?: bigint | string;
+}
+interface SendCallOpts extends CommonTxOpts {
+    /** Contract address, ase1 or 0x hex. */
+    to: string;
+    /** Method name. */
     method: string;
-    /** Method arguments (passed as JSON to the contract). */
+    /**
+     * Arguments, sent as JSON. Every ase1 address string, at any depth, is
+     * converted to lowercase 0x hex before signing (contracts compare with hex
+     * msg.sender).
+     */
     args?: unknown[];
-    /** ASE to attach to the call (default: 0). */
+    /**
+     * ASE to send with the call, parsed with parseAse: "1.5" or 2 is ASE, a
+     * bigint is wei (and an integer string over 18 digits is wei). Prefer
+     * `valueWei` for exact values.
+     */
     value?: string | number | bigint;
-    /** Override the gas limit. Default: 2,000,000. */
-    gasLimit?: bigint;
-    /** Override the nonce. Default: auto-fetched. */
-    nonce?: bigint;
+    /** Value in wei. Takes precedence over `value`. */
+    valueWei?: bigint | string;
 }
-interface DeployOpts {
-    /** The JavaScript source code of the contract. */
+interface DeployOpts extends CommonTxOpts {
+    /** The contract's JavaScript source. */
     source: string;
-    /** ASE to attach to the deploy (default: 0). */
+    /** ASE to send with the deploy, parsed like SendCallOpts.value. */
     value?: string | number | bigint;
-    /** Override the gas limit. Default: based on source length. */
-    gasLimit?: bigint;
-    /** Override the nonce. Default: auto-fetched. */
-    nonce?: bigint;
+    /** Value in wei. Takes precedence over `value`. */
+    valueWei?: bigint | string;
+}
+/** A signed transaction that has not been submitted (see sign* and sendBatch). */
+interface SignedTx {
+    /** 0x hex wire bytes, what POST /tx takes. */
+    rawTx: string;
+    /** The transaction hash (0x hex, BLAKE3 of rawTx). Hashes stay hex: there is no ase1 form. */
+    hash: string;
+    nonce: bigint;
+    /** ase1 of the signer. */
+    from: string;
+    /** For a deploy: the new contract's address (ase1). */
+    contractAddress?: string;
 }
 interface SentTx {
-    /** The transaction hash (0x-prefixed). */
+    /** The transaction hash (0x hex). */
     hash: string;
-    /** Wait for the transaction to be included in a block. */
-    wait(timeoutMs?: number): Promise<Receipt>;
+    nonce: bigint;
+    /** ase1 of the signer. */
+    from: string;
+    /** For a deploy: the new contract's address (ase1). */
+    contractAddress?: string;
+    /**
+     * Wait for the receipt.
+     *
+     *   await tx.wait()                     // first receipt: in a block (default, as in 0.1.x)
+     *   await tx.wait(30_000)               // same, 30 s timeout (0.1.x signature)
+     *   await tx.wait({ until: 'final' })   // only once its block is final
+     *
+     * Resolves with the receipt even when it has success: false (as in 0.1.x);
+     * pass `{ throwOnFailure: true }` to reject with TxFailedError instead.
+     * Default timeout: 60 s ("included"), 120 s ("final"); rejects with
+     * TimeoutError, which does not mean the transaction failed.
+     */
+    wait(timeoutOrOpts?: number | WaitOptions): Promise<Receipt>;
+}
+interface BatchSendResult {
+    accepted: number;
+    rejected: number;
+    total: number;
+    /** Same order as the input. Rejected entries have accepted: false and a reason; they will not land. */
+    results: Array<TxResult & {
+        hash: string;
+        nonce: bigint;
+        wait: SentTx['wait'];
+    }>;
 }
 declare class AsentumWallet {
     readonly client: AsentumClient;
     readonly keypair: Dilithium3Keypair;
+    /**
+     * The wallet's address as ase1. (0.1.x returned checksummed 0x hex here;
+     * use `addressHex` for the hex form.)
+     */
     readonly address: string;
+    /** The same address as lowercase 0x hex: what contracts see as msg.sender. */
+    readonly addressHex: string;
+    /** Key-less mode for transactions from this wallet. */
+    keyless: KeylessMode;
+    private readonly addressBytes;
+    private nextNonce?;
+    private queue;
+    private keyOnRecord;
+    private keyCheckedAt;
     private constructor();
-    /** Create a wallet with a random Dilithium3 keypair. */
-    static create(client: AsentumClient): AsentumWallet;
-    /** Create a wallet from a 32-byte seed. */
-    static fromSeed(client: AsentumClient, seed: Uint8Array): AsentumWallet;
-    /** Create a wallet from a hex-encoded secret key. */
-    static fromSecretKey(client: AsentumClient, secretKeyHex: string, publicKeyHex: string): AsentumWallet;
-    /** Get the secret key as a hex string (for export/backup). */
+    /** A wallet with a random keypair. */
+    static create(client: AsentumClient, opts?: WalletOptions): AsentumWallet;
+    /** A wallet from a seed (the first 32 bytes are used). Same seed, same keys. */
+    static fromSeed(client: AsentumClient, seed: Uint8Array, opts?: WalletOptions): AsentumWallet;
+    /** A wallet from exported hex keys (secretKeyHex / publicKeyHex). */
+    static fromSecretKey(client: AsentumClient, secretKeyHex: string, publicKeyHex: string, opts?: WalletOptions): AsentumWallet;
+    /** The secret key as hex, for backup. Treat it like a password. */
     get secretKeyHex(): string;
-    /** Get the public key as a hex string. */
+    /** The public key as hex. */
     get publicKeyHex(): string;
-    /** Get the current balance in wei. */
+    /** Balance in wei. */
     getBalance(): Promise<bigint>;
-    /** Get the current nonce. */
+    /** The node's pendingNonce for this wallet (the nonce the next transaction would use, ignoring local allocations). */
     getNonce(): Promise<bigint>;
-    /** Request test ASE from the faucet. */
+    /**
+     * Forget locally allocated nonces; the next transaction asks the node
+     * again. The wallet does this itself after a rejection.
+     */
+    resetNonce(): void;
+    /**
+     * @deprecated POST /dev/faucet is off on every public node (see
+     * AsentumClient.faucet). Use the airdrop dashboard for test ASE.
+     */
     requestFaucet(amount?: string): Promise<TxResult>;
-    /** Send ASE to another address. */
+    /** Send ASE. Throws TxRejectedError when the node does not accept it. */
     sendTransfer(opts: SendTransferOpts): Promise<SentTx>;
-    /** Call a method on a deployed contract (state-changing). */
+    /** Call a contract method (state-changing). Throws TxRejectedError when the node does not accept it. */
     sendCall(opts: SendCallOpts): Promise<SentTx>;
-    /** Deploy a new smart contract. Returns an AsentumContract instance. */
+    /**
+     * Same as sendCall, but `value` is in wei. Use this when you hold wei
+     * amounts (balances, contract return values) so nothing is reinterpreted.
+     */
+    sendCallWei(opts: Omit<SendCallOpts, 'value' | 'valueWei'> & {
+        value?: bigint | string;
+    }): Promise<SentTx>;
+    /** Same as sendTransfer, but `amount` is in wei. */
+    sendTransferWei(opts: Omit<SendTransferOpts, 'amount' | 'amountWei'> & {
+        amount: bigint | string;
+    }): Promise<SentTx>;
+    /**
+     * Deploy a contract. Returns an AsentumContract at the derived address
+     * right away; the deploy is only accepted, so `await contract.waitForDeploy()`
+     * before using it.
+     */
     deploy(sourceOrOpts: string | DeployOpts): Promise<AsentumContract>;
-    private signAndSubmit;
+    /** Sign a transfer without submitting it (allocates the next nonce unless given). */
+    signTransfer(opts: SendTransferOpts): Promise<SignedTx>;
+    /** Sign a contract call without submitting it. */
+    signCall(opts: SendCallOpts): Promise<SignedTx>;
+    /** Sign a deploy without submitting it. `contractAddress` is the address it will get. */
+    signDeploy(opts: DeployOpts): Promise<SignedTx>;
+    /**
+     * Submit several signed transactions in one request (POST /tx/batch), in
+     * the given order. Sign them first with signTransfer / signCall /
+     * signDeploy (consecutive calls get consecutive nonces). One rejection
+     * does not stop the rest, but a nonce gap leaves later ones waiting.
+     * Does not throw on rejections: check each result.
+     */
+    sendBatch(txs: SignedTx[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<BatchSendResult>;
+    /** Run fn after every earlier send/sign of this wallet, so nonces are handed out in order. */
+    private serial;
+    private allocateNonce;
+    private useKeyless;
+    private build;
+    private buildTransfer;
+    private buildCall;
+    private buildDeploy;
+    private submit;
 }
+/** The address a deploy from `sender` with `nonce` gets (ase1). */
+declare function getContractAddress(sender: string, nonce: bigint | number): string;
+
+/**
+ * If `s` is a valid ase1 address (bech32 checksum OK, HRP exactly "ase",
+ * 20-byte payload, single case, no surrounding whitespace) return its
+ * lowercase `0x` hex form. Otherwise return null.
+ */
+declare function ase1ToHexOrNull(s: string): string | null;
+/** ase1 to lowercase 0x hex, or null when the checksum or length is wrong. Same as ase1ToHexOrNull. */
+declare function ase1ToHex(s: string): string | null;
+/** True for a well-formed ase1 address with a valid checksum. */
+declare function isAse1(s: unknown): boolean;
+/** True for a 0x hex address (20 bytes, any case). */
+declare function isHexAddress(s: unknown): boolean;
+/** True for either accepted address form. */
+declare function isAddress(s: unknown): boolean;
+/** 0x hex (20 bytes) to ase1. Returns '' when the input is not a hex address (same as @asentum/connect). */
+declare function hexToAse1(hex: string): string;
+/**
+ * Any address (hex or ase1) to lowercase ase1, for display. Input that is
+ * not an address is returned unchanged (empty string for null/undefined).
+ */
+declare function toAse1(a: string | null | undefined): string;
+/**
+ * Any address (hex or ase1) to lowercase 0x hex: the form contracts use.
+ * Throws InvalidAddress-style Error on anything else.
+ */
+declare function toHexAddress(a: string): string;
+/** Parse either address form into 20 raw bytes. Throws on invalid input. */
+declare function addressToBytes(a: string): Uint8Array;
+/** 20 raw bytes to ase1. */
+declare function bytesToAse1(bytes: Uint8Array): string;
+/** Shortened ase1 for buttons and chips, e.g. ase1qxyz12...ab34cd. */
+declare function shortAse1(a: string | null | undefined, lead?: number, tail?: number): string;
+/**
+ * Recursively walk contract call arguments (arrays and plain objects,
+ * values only, never keys) and replace every string that is a valid ase1
+ * address with its lowercase `0x` hex form. Everything else is returned
+ * unchanged. The input is never mutated; a new structure is returned.
+ * Idempotent: hex input stays hex.
+ *
+ * Why: contract code runs with hex. `msg.sender` is lowercase `0x...`, so an
+ * ase1 string stored by a contract would never match that person's sender.
+ * The SDK applies this to every call it signs and every view it sends.
+ */
+declare function ase1ArgsToHex<T>(value: T): T;
+
+/**
+ * Typed errors. Every error the SDK throws on purpose extends AsentumError,
+ * so `err instanceof AsentumError` separates SDK errors from bugs, and the
+ * `code` string is stable for switch statements.
+ */
+
+type AsentumErrorCode = 'HTTP_ERROR' | 'RATE_LIMITED' | 'NETWORK_ERROR' | 'RPC_ERROR' | 'JSON_RPC_ERROR' | 'TX_REJECTED' | 'TX_FAILED' | 'TIMEOUT' | 'ABORTED' | 'VIEW_FAILED' | 'INVALID_ARGUMENT';
+declare class AsentumError extends Error {
+    readonly code: AsentumErrorCode;
+    constructor(code: AsentumErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The node or gateway answered with a non-2xx HTTP status. */
+declare class HttpError extends AsentumError {
+    readonly status: number;
+    readonly url: string;
+    /** Parsed JSON body when there was one, otherwise the text (the gateway sends HTML for 429). */
+    readonly body: unknown;
+    constructor(status: number, url: string, body: unknown, message?: string, code?: AsentumErrorCode);
+}
+/**
+ * HTTP 429. The public gateway allows about 25 requests a second per IP and
+ * answers 429 with an HTML page and no Retry-After; a node's own block-read
+ * budget answers JSON with Retry-After. The SDK already retried with backoff
+ * before throwing this.
+ */
+declare class RateLimitError extends HttpError {
+    /** From the Retry-After header, when the server sent one. */
+    readonly retryAfterMs?: number;
+    constructor(url: string, body: unknown, retryAfterMs?: number);
+}
+/** fetch itself failed (DNS, connection reset, CORS, per-request timeout). */
+declare class NetworkError extends AsentumError {
+    readonly url: string;
+    constructor(url: string, cause: unknown);
+}
+/**
+ * HTTP 200 with an error body. Most node errors look like this: a bad
+ * address, a bad tx hash, a governance read that failed. (A missing receipt
+ * or block is NOT an error: those methods return null.)
+ */
+declare class RpcError extends AsentumError {
+    readonly path: string;
+    readonly body: unknown;
+    constructor(path: string, message: string, body: unknown);
+}
+/** A JSON-RPC (POST /) error object. */
+declare class JsonRpcError extends AsentumError {
+    readonly rpcCode: number;
+    readonly method: string;
+    readonly data?: unknown;
+    constructor(method: string, rpcCode: number, message: string, data?: unknown);
+}
+/**
+ * POST /tx answered `accepted: false`. The transaction never reached the
+ * mempool and will not land. `reason` is the node's text, for example
+ * "stale nonce: account is at 153, tx has 152" or "insufficient balance".
+ */
+declare class TxRejectedError extends AsentumError {
+    readonly reason: string;
+    /** The locally computed hash of the rejected transaction (it is not on chain). */
+    readonly txHash?: string;
+    constructor(reason: string, txHash?: string);
+    /** True when the reason is about the nonce (stale, too far ahead, duplicate nonce). */
+    get isNonceError(): boolean;
+}
+/** The transaction is in a block but ran and failed (`success: false`). */
+declare class TxFailedError extends AsentumError {
+    readonly receipt: Receipt;
+    constructor(receipt: Receipt);
+}
+/**
+ * Waiting ran out of time. This is NOT a failure: the transaction may still
+ * land. `lastReceipt` is set when it was seen in a block but not final yet.
+ */
+declare class TimeoutError extends AsentumError {
+    readonly txHash: string;
+    readonly lastReceipt: Receipt | null;
+    constructor(txHash: string, timeoutMs: number, until: string, lastReceipt: Receipt | null);
+}
+/** The caller's AbortSignal fired. `name` is "AbortError", as with fetch. */
+declare class AbortError extends AsentumError {
+    constructor(message?: string);
+}
+/** POST /view answered `ok: false` (method missing, contract threw, bad blockTag). */
+declare class ViewError extends AsentumError {
+    readonly method: string;
+    readonly reason: string;
+    constructor(method: string, reason: string);
+}
+
+/**
+ * @asentum/sdk: TypeScript SDK for building on Asentum.
+ *
+ *   - {@link AsentumClient}: reads, submission of signed transactions, waitForReceipt
+ *   - {@link AsentumWallet}: keypair, signing, nonces, sending
+ *   - {@link AsentumContract}: view, send and events for one contract
+ *
+ * ```ts
+ * import { AsentumClient, AsentumWallet } from '@asentum/sdk';
+ *
+ * const client = new AsentumClient('https://testnet.asentum.com');
+ * const { finalized, tip } = await client.getHeads();
+ *
+ * const wallet = AsentumWallet.fromSecretKey(client, SECRET_HEX, PUBLIC_HEX);
+ * const tx = await wallet.sendTransfer({ to: 'ase1...', amountWei: 10n ** 18n });
+ * await tx.wait();                    // in a block (about 2.5 s)
+ * await tx.wait({ until: 'final' });  // final (a few blocks later)
+ * ```
+ */
+
+/** SDK version. */
+declare const VERSION = "0.2.0";
 
-export { AsentumClient, AsentumContract, AsentumWallet, type Balance, type Block, type BlockHeader, type ChainInfo, type DeployOpts, type Metadata, type Receipt, type SendCallOpts, type SendTransferOpts, type SentTx, type Transaction, type TxResult, type ValidatorInfo, type ViewCallResult, formatAse, parseAse };
+export { AbortError, type AccountInfo, type ApiInfo, AsentumClient, AsentumContract, AsentumError, type AsentumErrorCode, AsentumWallet, type Balance, type BatchSendResult, type BatchTxResult, type Block, type BlockHeader, type BlockOptions, type BlockReceipts, type BlockTag, type CallOptions, type ChainInfo, type ClientOptions, type Committee, type CommitteeState, type ContractSendOpts, DEFAULT_RPC, type DeployOpts, type Dilithium3Keypair, type EpochInfo, type EthTransaction, type FetchLike, type FinalizedStatus, GOVERNANCE_CONTRACT, type GovernanceLocked, type GovernanceProposal, type GovernanceProposalDetail, type GovernanceWithdrawable, type Heads, HttpError, JsonRpcError, type KeylessMode, type Liveness, type LivenessEntry, type Log, type LogFilter, MAX_LOG_RANGE, type Metadata, NetworkError, type Participation, type ParticipationEntry, type PublicKeyStatus, RateLimitError, type Receipt, type ReceiptEvent, type ReceiptOptions, RpcError, type SendCallOpts, type SendTransferOpts, type SentTx, type SignedTx, TimeoutError, type Tombstones, type Transaction, type TransportOptions, TxFailedError, TxRejectedError, type TxResult, VERSION, type ValidatorInfo, type ValidatorsResponse, type ViewCallResult, ViewError, type ViewOptions, type WaitOptions, type WaitUntil, type WalletOptions, addressToBytes, ase1ArgsToHex, ase1ToHex, ase1ToHexOrNull, aseToWei, bytesToAse1, eventTopic, formatAddress, formatAse, getContractAddress, hexToAse1, isAddress, isAse1, isHexAddress, parseAse, shortAse1, toAse1, toHexAddress, toWei };