@asentum/sdk 0.1.0

package/src/wallet.ts

@@ -0,0 +1,352 @@
+// Copyright 2026 The AsentumChain Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * AsentumWallet — a keypair-backed client that can sign and submit
+ * transactions. Extends AsentumClient with signing capabilities.
+ *
+ * Usage:
+ *
+ *   // Create a random wallet
+ *   const wallet = AsentumWallet.create(client);
+ *
+ *   // Or from an existing private key (hex)
+ *   const wallet = AsentumWallet.fromSecretKey(client, '0x...');
+ *
+ *   // Or from a 32-byte seed
+ *   const wallet = AsentumWallet.fromSeed(client, seed);
+ *
+ *   // Send ASE
+ *   const tx = await wallet.sendTransfer({ to: '0x...', amount: '1.5' });
+ *
+ *   // Deploy a contract
+ *   const contract = await wallet.deploy('function init() { ... }');
+ *
+ *   // Call a contract method (write)
+ *   const tx2 = await wallet.sendCall({
+ *     to: contract.address,
+ *     method: 'transfer',
+ *     args: ['0xbob...', '100'],
+ *   });
+ */
+
+import {
+  generateKeypair,
+  addressFromPublicKey,
+  type Dilithium3Keypair,
+} from '@asentum/crypto';
+import {
+  SignedTransactionSchema,
+  TransactionBodySchema,
+} from '@asentum/types';
+import { blake3, sign } from '@asentum/crypto';
+import { AsentumClient, type TxResult } from './client.js';
+import { AsentumContract } from './contract.js';
+
+// ---------------------------------------------------------------------------
+// Hex helpers
+// ---------------------------------------------------------------------------
+
+function bytesToHex(bytes: Uint8Array): string {
+  let hex = '0x';
+  for (let i = 0; i < bytes.length; i++) {
+    hex += (bytes[i] ?? 0).toString(16).padStart(2, '0');
+  }
+  return hex;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  let h = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+  if (h.length % 2 !== 0) h = '0' + h;
+  const out = new Uint8Array(h.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+function hexToAddress20(hex: string): Uint8Array {
+  const bytes = hexToBytes(hex);
+  if (bytes.length !== 20) throw new Error(`expected 20-byte address, got ${bytes.length}`);
+  return bytes;
+}
+
+// ---------------------------------------------------------------------------
+// Amount parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an ASE amount string into wei (bigint).
+ * Accepts: "1", "1.5", "0.001", or a raw wei integer string.
+ */
+export function parseAse(amount: string | number | bigint): bigint {
+  if (typeof amount === 'bigint') return amount;
+  if (typeof amount === 'number') return BigInt(Math.floor(amount * 1e18));
+  const s = amount.trim();
+  if (/^\d+$/.test(s)) {
+    // If it's a very large integer, treat as wei. Otherwise ASE.
+    if (s.length > 18) return BigInt(s); // likely wei
+    return BigInt(s) * 1000000000000000000n; // ASE → wei
+  }
+  if (/^\d+\.\d{1,18}$/.test(s)) {
+    const [whole, frac = ''] = s.split('.');
+    const padded = frac.padEnd(18, '0').slice(0, 18);
+    return BigInt(whole + padded);
+  }
+  throw new Error(`invalid amount: "${amount}" — use "1", "1.5", or a wei integer`);
+}
+
+/**
+ * Format a wei bigint as a human-readable ASE string.
+ */
+export function formatAse(wei: bigint | string): string {
+  const w = typeof wei === 'bigint' ? wei : BigInt(wei);
+  const whole = w / 1000000000000000000n;
+  const frac = w % 1000000000000000000n;
+  if (frac === 0n) return whole.toString();
+  const fracStr = frac.toString().padStart(18, '0').replace(/0+$/, '');
+  return `${whole}.${fracStr}`;
+}
+
+// ---------------------------------------------------------------------------
+// Transaction building
+// ---------------------------------------------------------------------------
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export interface SentTx {
+  /** The transaction hash (0x-prefixed). */
+  hash: string;
+  /** Wait for the transaction to be included in a block. */
+  wait(timeoutMs?: number): Promise<import('./client.js').Receipt>;
+}
+
+// ---------------------------------------------------------------------------
+// AsentumWallet
+// ---------------------------------------------------------------------------
+
+export class AsentumWallet {
+  readonly client: AsentumClient;
+  readonly keypair: Dilithium3Keypair;
+  readonly address: string;
+
+  private constructor(client: AsentumClient, keypair: Dilithium3Keypair) {
+    this.client = client;
+    this.keypair = keypair;
+    this.address = addressFromPublicKey(keypair.publicKey);
+  }
+
+  /** Create a wallet with a random Dilithium3 keypair. */
+  static create(client: AsentumClient): AsentumWallet {
+    const seed = new Uint8Array(32);
+    crypto.getRandomValues(seed);
+    const keypair = generateKeypair(seed);
+    return new AsentumWallet(client, keypair);
+  }
+
+  /** Create a wallet from a 32-byte seed. */
+  static fromSeed(client: AsentumClient, seed: Uint8Array): AsentumWallet {
+    if (seed.length < 32) throw new Error('seed must be at least 32 bytes');
+    const keypair = generateKeypair(seed.slice(0, 32));
+    return new AsentumWallet(client, keypair);
+  }
+
+  /** Create a wallet from a hex-encoded secret key. */
+  static fromSecretKey(client: AsentumClient, secretKeyHex: string, publicKeyHex: string): AsentumWallet {
+    return new AsentumWallet(client, {
+      secretKey: hexToBytes(secretKeyHex),
+      publicKey: hexToBytes(publicKeyHex),
+    });
+  }
+
+  /** Get the secret key as a hex string (for export/backup). */
+  get secretKeyHex(): string {
+    return bytesToHex(this.keypair.secretKey);
+  }
+
+  /** Get the public key as a hex string. */
+  get publicKeyHex(): string {
+    return bytesToHex(this.keypair.publicKey);
+  }
+
+  /** Get the current balance in wei. */
+  async getBalance(): Promise<bigint> {
+    const bal = await this.client.getBalance(this.address);
+    return BigInt(bal.balance);
+  }
+
+  /** Get the current nonce. */
+  async getNonce(): Promise<bigint> {
+    return this.client.getNonce(this.address);
+  }
+
+  /** Request test ASE from the faucet. */
+  async requestFaucet(amount: string = '100000000000000000000'): Promise<TxResult> {
+    return this.client.faucet(this.address, amount);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Sending transactions
+  // ---------------------------------------------------------------------------
+
+  /** Send ASE to another address. */
+  async sendTransfer(opts: SendTransferOpts): Promise<SentTx> {
+    const chainId = await this.client.getChainId();
+    const nonce = opts.nonce ?? await this.getNonce();
+    const value = parseAse(opts.amount);
+
+    const body = {
+      chainId,
+      nonce,
+      maxPriorityFeePerGas: 0n,
+      maxFeePerGas: 1n,
+      gasLimit: opts.gasLimit ?? 21_000n,
+      to: hexToAddress20(opts.to),
+      value,
+      data: new Uint8Array(0),
+    };
+
+    return this.signAndSubmit(body);
+  }
+
+  /** Call a method on a deployed contract (state-changing). */
+  async sendCall(opts: SendCallOpts): Promise<SentTx> {
+    const chainId = await this.client.getChainId();
+    const nonce = opts.nonce ?? await this.getNonce();
+    const data = new TextEncoder().encode(
+      JSON.stringify({ method: opts.method, args: opts.args ?? [] }),
+    );
+
+    const body = {
+      chainId,
+      nonce,
+      maxPriorityFeePerGas: 0n,
+      maxFeePerGas: 1n,
+      gasLimit: opts.gasLimit ?? 2_000_000n,
+      to: hexToAddress20(opts.to),
+      value: opts.value ? parseAse(opts.value) : 0n,
+      data,
+    };
+
+    return this.signAndSubmit(body);
+  }
+
+  /** Deploy a new smart contract. Returns an AsentumContract instance. */
+  async deploy(sourceOrOpts: string | DeployOpts): Promise<AsentumContract> {
+    const opts: DeployOpts = typeof sourceOrOpts === 'string'
+      ? { source: sourceOrOpts }
+      : sourceOrOpts;
+
+    const chainId = await this.client.getChainId();
+    const nonce = opts.nonce ?? await this.getNonce();
+    const data = new TextEncoder().encode(opts.source);
+    const gasLimit = opts.gasLimit ?? BigInt(Math.max(2_000_000, 1000 * opts.source.length));
+
+    const body = {
+      chainId,
+      nonce,
+      maxPriorityFeePerGas: 0n,
+      maxFeePerGas: 1n,
+      gasLimit,
+      to: new Uint8Array(20), // zero address = deploy
+      value: opts.value ? parseAse(opts.value) : 0n,
+      data,
+    };
+
+    const sentTx = await this.signAndSubmit(body);
+
+    // Derive the contract address: blake3(sender || nonce), take first 20 bytes.
+    const senderBytes = hexToAddress20(this.address);
+    const nonceBytes = new Uint8Array(8);
+    new DataView(nonceBytes.buffer).setBigUint64(0, nonce, true);
+    const combined = new Uint8Array(20 + 8);
+    combined.set(senderBytes);
+    combined.set(nonceBytes, 20);
+    const hash = blake3(combined);
+    const contractAddress = bytesToHex(hash.slice(0, 20));
+
+    return new AsentumContract(this.client, contractAddress, sentTx, this);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal: sign + submit
+  // ---------------------------------------------------------------------------
+
+  private async signAndSubmit(body: {
+    chainId: bigint;
+    nonce: bigint;
+    maxPriorityFeePerGas: bigint;
+    maxFeePerGas: bigint;
+    gasLimit: bigint;
+    to: Uint8Array;
+    value: bigint;
+    data: Uint8Array;
+  }): Promise<SentTx> {
+    // Serialize → hash → sign → encode → submit
+    const bodyBytes = TransactionBodySchema.serialize(body);
+    const digest = blake3(bodyBytes);
+    const signature = sign(digest, this.keypair.secretKey);
+    const signedTx = {
+      body,
+      publicKey: this.keypair.publicKey,
+      signature,
+    };
+    const rawTxHex = bytesToHex(SignedTransactionSchema.serialize(signedTx));
+    const result = await this.client.submitRawTx(rawTxHex);
+
+    if (!result.accepted) {
+      throw new Error(`transaction rejected: ${result.reason || 'unknown reason'}`);
+    }
+
+    const txHash = result.txHash ?? '(unknown)';
+    const client = this.client;
+
+    return {
+      hash: txHash,
+      async wait(timeoutMs = 15_000): Promise<import('./client.js').Receipt> {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+          const receipt = await client.getReceipt(txHash);
+          if (receipt) return receipt;
+          await new Promise((r) => setTimeout(r, 1000));
+        }
+        throw new Error(`transaction ${txHash} not confirmed within ${timeoutMs}ms`);
+      },
+    };
+  }
+}