@asentum/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+import { Dilithium3Keypair } from '@asentum/crypto';
+
+/**
+ * AsentumClient — read-only interface to an Asentum node's RPC.
+ *
+ * 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.
+ *
+ * Works in Node.js (20+) and browsers — only depends on `fetch`.
+ */
+interface ChainInfo {
+    chainId: string;
+    height: number;
+    mempoolSize: number;
+    latestHeader: BlockHeader;
+}
+interface BlockHeader {
+    parentHash: string;
+    stateRoot: string;
+    transactionsRoot: string;
+    receiptsRoot: string;
+    number: string;
+    timestamp: string;
+    gasLimit: string;
+    gasUsed: string;
+    baseFeePerGas: string;
+    proposer: string;
+}
+interface Block {
+    header: BlockHeader;
+    hash?: string;
+    transactions: Transaction[];
+    receipts: Receipt[];
+}
+interface Transaction {
+    kind: 'transfer' | 'deploy' | 'call';
+    body: {
+        chainId: string;
+        nonce: string;
+        maxPriorityFeePerGas: string;
+        maxFeePerGas: string;
+        gasLimit: string;
+        to: string;
+        value: string;
+        dataSize: number;
+    };
+    call?: {
+        method: string;
+        args: unknown[];
+    };
+}
+interface Receipt {
+    txHash: string;
+    blockNumber: string;
+    txIndex: number;
+    sender: string;
+    recipient: string;
+    kind: string;
+    success: boolean;
+    gasUsed: string;
+    events: Array<{
+        name: string;
+        data: unknown;
+    }>;
+    returnValue?: unknown;
+}
+interface Balance {
+    address: string;
+    balance: string;
+    nonce: string;
+}
+interface ValidatorInfo {
+    address: string;
+    stake: string;
+    bondedAt: string;
+    pubKeySize: number;
+}
+interface ViewCallResult {
+    ok: boolean;
+    reason?: string;
+    returnValue?: unknown;
+    gasUsed?: string;
+    events?: Array<{
+        name: string;
+        data: unknown;
+    }>;
+}
+interface TxResult {
+    accepted: boolean;
+    reason?: string;
+    txHash?: string;
+}
+interface Metadata {
+    chainId: string;
+    chainName: string;
+    chainIdDecimal: string;
+    currentBlock: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrls: string[];
+    blockExplorerUrls: string[];
+    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;
+}
+
+/**
+ * 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);
+ *
+ *   // 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();
+ */
+
+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);
+    /**
+     * Call a view function (read-only, free, no transaction).
+     *
+     * @param method - The function name to call.
+     * @param args   - Arguments to pass to the function.
+     * @returns The return value of the function.
+     */
+    view(method: string, args?: unknown[]): Promise<unknown>;
+    /**
+     * Call a view function and return the full result including gas + events.
+     */
+    viewFull(method: string, args?: unknown[]): Promise<ViewCallResult>;
+    /**
+     * Send a state-changing transaction to the contract.
+     *
+     * @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()`.
+     */
+    send(method: string, args?: unknown[], opts?: {
+        value?: string | number | bigint;
+        gasLimit?: bigint;
+        nonce?: bigint;
+        wallet?: AsentumWallet;
+    }): Promise<SentTx>;
+    /**
+     * Attach a wallet to this contract for future send() calls.
+     */
+    connect(wallet: AsentumWallet): AsentumContract;
+    /**
+     * Get the source code of this contract as a UTF-8 string.
+     * Returns null if the address has no deployed code.
+     */
+    getSource(): Promise<string | null>;
+    /**
+     * Get the ASE balance of this contract.
+     */
+    getBalance(): Promise<bigint>;
+    /**
+     * Wait for the deploy transaction to be confirmed (if this contract
+     * was deployed in this session). Useful after `wallet.deploy()`.
+     */
+    waitForDeploy(timeoutMs?: number): Promise<Receipt>;
+}
+
+/**
+ * Parse an ASE amount string into wei (bigint).
+ * Accepts: "1", "1.5", "0.001", or a raw wei integer string.
+ */
+declare function parseAse(amount: string | number | bigint): bigint;
+/**
+ * Format a wei bigint as a human-readable ASE string.
+ */
+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. */
+    nonce?: bigint;
+}
+interface SendCallOpts {
+    /** Contract address (0x-prefixed, 40 hex chars). */
+    to: string;
+    /** Method name to call on the contract. */
+    method: string;
+    /** Method arguments (passed as JSON to the contract). */
+    args?: unknown[];
+    /** ASE to attach to the call (default: 0). */
+    value?: string | number | bigint;
+    /** Override the gas limit. Default: 2,000,000. */
+    gasLimit?: bigint;
+    /** Override the nonce. Default: auto-fetched. */
+    nonce?: bigint;
+}
+interface DeployOpts {
+    /** The JavaScript source code of the contract. */
+    source: string;
+    /** ASE to attach to the deploy (default: 0). */
+    value?: string | number | bigint;
+    /** Override the gas limit. Default: based on source length. */
+    gasLimit?: bigint;
+    /** Override the nonce. Default: auto-fetched. */
+    nonce?: bigint;
+}
+interface SentTx {
+    /** The transaction hash (0x-prefixed). */
+    hash: string;
+    /** Wait for the transaction to be included in a block. */
+    wait(timeoutMs?: number): Promise<Receipt>;
+}
+declare class AsentumWallet {
+    readonly client: AsentumClient;
+    readonly keypair: Dilithium3Keypair;
+    readonly address: string;
+    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). */
+    get secretKeyHex(): string;
+    /** Get the public key as a hex string. */
+    get publicKeyHex(): string;
+    /** Get the current balance in wei. */
+    getBalance(): Promise<bigint>;
+    /** Get the current nonce. */
+    getNonce(): Promise<bigint>;
+    /** Request test ASE from the faucet. */
+    requestFaucet(amount?: string): Promise<TxResult>;
+    /** Send ASE to another address. */
+    sendTransfer(opts: SendTransferOpts): Promise<SentTx>;
+    /** Call a method on a deployed contract (state-changing). */
+    sendCall(opts: SendCallOpts): Promise<SentTx>;
+    /** Deploy a new smart contract. Returns an AsentumContract instance. */
+    deploy(sourceOrOpts: string | DeployOpts): Promise<AsentumContract>;
+    private signAndSubmit;
+}
+
+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 };