shell-sdk 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.4.1] — 2026-04-25
+
+### Changed
+- `estimateBatch` JSDoc updated to reflect snake_case field names (`total_gas`, `inner_gas`) aligning with `shell-chain v0.18.1` wire format.
+
+## [0.4.0] — 2026-05-16
+
+### Added
+- **Native AA batch transactions** (`tx_type = 0x7E`): `buildBatchTransaction`, `buildSponsoredTransaction`, `buildInnerTransfer`, `buildInnerCall`, `hashBatchTransaction` in `transactions.ts`.
+  - `hashBatchTransaction` computes the `batch_signing_hash` (domain `0x42 || RLP(tx) || RLP(bundle)`), required for signing AA bundle txs.
+- **AA types** (`types.ts`): `AaInnerCall`, `AaBundle`, `ShellBatchInnerCallRequest`, `ShellEstimateBatchRequest`, `ShellEstimateBatchResult`, `ShellBatchInnerGas`, `ShellPaymasterPolicy`, `ShellIsSponsoredResult`.
+  - Constants: `AA_BUNDLE_TX_TYPE = 0x7e`, `AA_MAX_INNER_CALLS = 16`.
+  - `SignedShellTransaction` now has optional `aa_bundle?: AaBundle` field.
+- **AA provider methods** (`provider.ts`): `estimateBatch`, `getPaymasterPolicy`, `isSponsored`, `verifyWitnessRoot`.
+- **ML-DSA-65 canonical naming** (`signer.ts`): `"ML-DSA-65"` is now the first-class `SignatureTypeName` (FIPS 204). `"Dilithium3"` and `"MlDsa65"` remain as compatibility aliases, all mapping to algorithm ID `0`.
+  - `KEY_TYPE_TO_SIGNATURE_TYPE` now maps all ML-DSA-65 variants (including `"dilithium3"`) to `"ML-DSA-65"`.
+- **New exports** (`index.ts`): `SIGNATURE_TYPE_IDS`, `KEY_TYPE_TO_SIGNATURE_TYPE`, all new AA builders and types.
+
+### Changed
+- `SIGNATURE_TYPE_IDS`: `"MlDsa65"` now maps to `0` (was `1`) — aligns with chain algorithm ID; no wire-format change.
+
+### Compatibility
+- Fully backwards-compatible with `shell-chain v0.17.0` and prior SDK `0.3.x` usage.
+- AA fields (`aa_bundle`, new RPC methods) are only active on `shell-chain v0.18.0+`.
+
 ## [0.3.1] — 2026-04-23
 
 ### Changed

package/dist/adapters.js

@@ -164,6 +164,7 @@ export class SlhDsaAdapter {
  */
 export function generateAdapter(algorithm, seed) {
     switch (algorithm) {
+        case "ML-DSA-65":
         case "Dilithium3":
         case "MlDsa65":
             return MlDsa65Adapter.generate(seed);
@@ -189,6 +190,7 @@ export function generateAdapter(algorithm, seed) {
  */
 export function adapterFromKeyPair(algorithm, publicKey, secretKey) {
     switch (algorithm) {
+        case "ML-DSA-65":
         case "Dilithium3":
         case "MlDsa65":
             return MlDsa65Adapter.fromKeyPair(publicKey, secretKey);

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
 export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, type CreateShellPublicClientOptions, } from "./provider.js";
 export { accountManagerAddress, accountManagerHexAddress, clearValidationCodeSelector, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, isSystemContractAddress, rotateKeySelector, setValidationCodeSelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
-export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, } from "./transactions.js";
+export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS, buildBatchTransaction, buildClearValidationCodeTransaction, buildInnerCall, buildInnerTransfer, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSponsoredTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_AA_GAS_LIMIT, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashBatchTransaction, hashTransaction, type BuildBatchTransactionOptions, type BuildSponsoredTransactionOptions, } from "./transactions.js";
 export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, type ParsedShellKeystore, } from "./keystore.js";
 export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, type MlDsa65KeyPair, type SlhDsaKeyPair, } from "./adapters.js";
 export { buildShellSignature, publicKeyFromHex, ShellSigner, signatureTypeFromKeyType, type SignerAdapter, } from "./signer.js";
-export type { AddressLike, HexString, ShellAccessListItem, ShellCipherParams, ShellEncryptedKey, ShellNodeInfo, ShellSendTransactionParams, ShellKdfParams, ShellSignature, ShellStorageProfile, ShellTransactionRequest, ShellTxByAddressPage, ShellTxWitness, ShellWitnessBundle, SignedShellTransaction, SignatureTypeName, } from "./types.js";
+export type { AaBundle, AaInnerCall, AddressLike, HexString, ShellAccessListItem, ShellBatchInnerCallRequest, ShellBatchInnerGas, ShellCipherParams, ShellEncryptedKey, ShellEstimateBatchRequest, ShellEstimateBatchResult, ShellIsSponsoredResult, ShellKdfParams, ShellNodeInfo, ShellPaymasterPolicy, ShellSendTransactionParams, ShellSignature, ShellStorageProfile, ShellTransactionRequest, ShellTxByAddressPage, ShellTxWitness, ShellWitnessBundle, ShellWitnessRootResult, SignedShellTransaction, SignatureTypeName, } from "./types.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { bytesToHexAddress, PQ_ADDRESS_HRP, PQ_ADDRESS_LENGTH, PQ_ADDRESS_VERSION_V1, bytesToPqAddress, derivePqAddressFromPublicKey, isPqAddress, normalizeHexAddress, normalizePqAddress, pqAddressVersion, pqAddressToBytes, } from "./address.js";
 export { createShellProvider, createShellPublicClient, createShellWsClient, ShellProvider, shellDevnet, } from "./provider.js";
 export { accountManagerAddress, accountManagerHexAddress, clearValidationCodeSelector, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, isSystemContractAddress, rotateKeySelector, setValidationCodeSelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
-export { buildClearValidationCodeTransaction, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashTransaction, } from "./transactions.js";
+export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS, buildBatchTransaction, buildClearValidationCodeTransaction, buildInnerCall, buildInnerTransfer, buildRotateKeyTransaction, buildSetValidationCodeTransaction, buildSignature, buildSignedTransaction, buildSponsoredTransaction, buildSystemTransaction, buildTransaction, buildTransferTransaction, DEFAULT_AA_GAS_LIMIT, DEFAULT_MAX_FEE_PER_GAS, DEFAULT_MAX_PRIORITY_FEE_PER_GAS, DEFAULT_SYSTEM_GAS_LIMIT, DEFAULT_TRANSFER_GAS_LIMIT, DEFAULT_TX_TYPE, hashBatchTransaction, hashTransaction, } from "./transactions.js";
 export { assertSignerMatchesKeystore, decryptKeystore, exportEncryptedKeyJson, parseEncryptedKey, validateEncryptedKeyAddress, } from "./keystore.js";
 export { adapterFromKeyPair, generateAdapter, generateMlDsa65KeyPair, generateSlhDsaKeyPair, MlDsa65Adapter, SlhDsaAdapter, } from "./adapters.js";
 export { buildShellSignature, publicKeyFromHex, ShellSigner, signatureTypeFromKeyType, } from "./signer.js";

package/dist/keystore.js

@@ -18,7 +18,7 @@ import { argon2id } from "hash-wasm";
 import { derivePqAddressFromPublicKey, normalizeHexAddress, normalizePqAddress } from "./address.js";
 import { adapterFromKeyPair } from "./adapters.js";
 import { ShellSigner, publicKeyFromHex, signatureTypeFromKeyType } from "./signer.js";
-const SIG_IDS = { Dilithium3: 0, MlDsa65: 1, SphincsSha2256f: 2 };
+const SIG_IDS = { "ML-DSA-65": 0, Dilithium3: 0, MlDsa65: 0, SphincsSha2256f: 2 };
 /**
  * Parse a Shell keystore file (string or object) and extract public metadata.
  *

package/dist/provider.d.ts

@@ -16,7 +16,7 @@
  * @module provider
  */
 import { type Chain, type PublicClient } from "viem";
-import type { ShellNodeInfo, ShellStorageProfile, ShellWitnessBundle, SignedShellTransaction } from "./types.js";
+import type { ShellEstimateBatchRequest, ShellEstimateBatchResult, ShellIsSponsoredResult, ShellNodeInfo, ShellPaymasterPolicy, ShellStorageProfile, ShellWitnessBundle, ShellWitnessRootResult, SignedShellTransaction } from "./types.js";
 /**
  * Pre-configured viem chain definition for Shell Devnet.
  *
@@ -183,6 +183,60 @@ export declare class ShellProvider {
      *   `undefined` if the node does not report it.
      */
     getStorageProfile(): Promise<ShellStorageProfile | undefined>;
+    /**
+     * Estimate gas for a native AA batch transaction.
+     *
+     * Calls `shell_estimateBatch`.
+     *
+     * @param request - Batch estimate request with inner calls and optional paymaster.
+     * @returns Gas estimates including `total_gas`, `per_inner`, and breakdown fields.
+     *
+     * @example
+     * ```typescript
+     * const estimate = await provider.estimateBatch({
+     *   inner_calls: [{ to: "pq1…", value: "0x0", gas_limit: "0x5208" }],
+     * });
+     * const totalGas = parseInt(estimate.total_gas, 16);
+     * ```
+     */
+    estimateBatch(request: ShellEstimateBatchRequest): Promise<ShellEstimateBatchResult>;
+    /**
+     * Fetch the paymaster policy for an address.
+     *
+     * Calls `shell_getPaymasterPolicy`. Any address returns a default `eoa-open`
+     * policy even if not explicitly registered as a paymaster.
+     *
+     * @param address - Paymaster address to query.
+     * @returns Paymaster policy object.
+     */
+    getPaymasterPolicy(address: string): Promise<ShellPaymasterPolicy>;
+    /**
+     * Check whether a transaction is sponsored by a paymaster.
+     *
+     * Calls `shell_isSponsored`. Returns `{ found: false, … }` for unknown hashes
+     * without throwing.
+     *
+     * @param txHash - Transaction hash to query (`0x`-prefixed).
+     * @returns Sponsorship details including found status, paymaster address, and inner call count.
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.isSponsored("0xabcd…");
+     * if (result.found && result.sponsored) {
+     *   console.log("gas paid by", result.paymaster);
+     * }
+     * ```
+     */
+    isSponsored(txHash: string): Promise<ShellIsSponsoredResult>;
+    /**
+     * Verify the witness root stored in a block header against the bundle.
+     *
+     * Calls `shell_verifyWitnessRoot`.
+     *
+     * @param blockNumberOrTag - Hex block number or `"latest"`.
+     * @returns Verification result object `{ block, witnessRoot, bundleRoot, match }`.
+     */
+    verifyWitnessRoot(blockNumberOrTag: string): Promise<ShellWitnessRootResult>;
 }
 /**
  * Create a viem `PublicClient` connected to Shell Chain over HTTP.

package/dist/provider.js

@@ -172,6 +172,69 @@ export class ShellProvider {
         const info = await this.getNodeInfo();
         return info.storage_profile;
     }
+    // ── AA methods (v0.18.0) ──────────────────────────────────────────────────
+    /**
+     * Estimate gas for a native AA batch transaction.
+     *
+     * Calls `shell_estimateBatch`.
+     *
+     * @param request - Batch estimate request with inner calls and optional paymaster.
+     * @returns Gas estimates including `total_gas`, `per_inner`, and breakdown fields.
+     *
+     * @example
+     * ```typescript
+     * const estimate = await provider.estimateBatch({
+     *   inner_calls: [{ to: "pq1…", value: "0x0", gas_limit: "0x5208" }],
+     * });
+     * const totalGas = parseInt(estimate.total_gas, 16);
+     * ```
+     */
+    async estimateBatch(request) {
+        return this.request("shell_estimateBatch", [request]);
+    }
+    /**
+     * Fetch the paymaster policy for an address.
+     *
+     * Calls `shell_getPaymasterPolicy`. Any address returns a default `eoa-open`
+     * policy even if not explicitly registered as a paymaster.
+     *
+     * @param address - Paymaster address to query.
+     * @returns Paymaster policy object.
+     */
+    async getPaymasterPolicy(address) {
+        return this.request("shell_getPaymasterPolicy", [address]);
+    }
+    /**
+     * Check whether a transaction is sponsored by a paymaster.
+     *
+     * Calls `shell_isSponsored`. Returns `{ found: false, … }` for unknown hashes
+     * without throwing.
+     *
+     * @param txHash - Transaction hash to query (`0x`-prefixed).
+     * @returns Sponsorship details including found status, paymaster address, and inner call count.
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.isSponsored("0xabcd…");
+     * if (result.found && result.sponsored) {
+     *   console.log("gas paid by", result.paymaster);
+     * }
+     * ```
+     */
+    async isSponsored(txHash) {
+        return this.request("shell_isSponsored", [txHash]);
+    }
+    /**
+     * Verify the witness root stored in a block header against the bundle.
+     *
+     * Calls `shell_verifyWitnessRoot`.
+     *
+     * @param blockNumberOrTag - Hex block number or `"latest"`.
+     * @returns Verification result object `{ block, witnessRoot, bundleRoot, match }`.
+     */
+    async verifyWitnessRoot(blockNumberOrTag) {
+        return this.request("shell_verifyWitnessRoot", [blockNumberOrTag]);
+    }
 }
 /**
  * Create a viem `PublicClient` connected to Shell Chain over HTTP.

package/dist/signer.d.ts

@@ -4,9 +4,10 @@ import type { SignedShellTransaction, SignatureTypeName } from "./types.js";
  * Maps each {@link SignatureTypeName} to its numeric algorithm ID used in
  * address derivation and on-chain records.
  *
- * - `Dilithium3` → `0`
- * - `MlDsa65` → `1`
- * - `SphincsSha2256f` → `2`
+ * - `"ML-DSA-65"` → `0` (canonical FIPS 204 name)
+ * - `"Dilithium3"` → `0` (legacy alias, same algorithm)
+ * - `"MlDsa65"` → `0` (camelCase alias, same algorithm)
+ * - `"SphincsSha2256f"` → `2`
  */
 export declare const SIGNATURE_TYPE_IDS: Record<SignatureTypeName, number>;
 /**
@@ -14,6 +15,7 @@ export declare const SIGNATURE_TYPE_IDS: Record<SignatureTypeName, number>;
  * corresponding {@link SignatureTypeName}.
  *
  * Keys are lowercase; matching is done after calling `.toLowerCase()`.
+ * Always returns the FIPS 204 canonical name `"ML-DSA-65"` for ML-DSA-65 variants.
  */
 export declare const KEY_TYPE_TO_SIGNATURE_TYPE: Record<string, SignatureTypeName>;
 /**
@@ -116,6 +118,7 @@ export declare class ShellSigner {
     buildSignedTransaction(options: Omit<BuildSignedTransactionOptions, "from" | "signature" | "signatureType"> & {
         txHash: Uint8Array;
         includePublicKey?: boolean;
+        aaBundle?: import("./types.js").AaBundle;
     }): Promise<SignedShellTransaction>;
 }
 /**

package/dist/signer.js

@@ -16,13 +16,15 @@ import { buildSignature, buildSignedTransaction, } from "./transactions.js";
  * Maps each {@link SignatureTypeName} to its numeric algorithm ID used in
  * address derivation and on-chain records.
  *
- * - `Dilithium3` → `0`
- * - `MlDsa65` → `1`
- * - `SphincsSha2256f` → `2`
+ * - `"ML-DSA-65"` → `0` (canonical FIPS 204 name)
+ * - `"Dilithium3"` → `0` (legacy alias, same algorithm)
+ * - `"MlDsa65"` → `0` (camelCase alias, same algorithm)
+ * - `"SphincsSha2256f"` → `2`
  */
 export const SIGNATURE_TYPE_IDS = {
+    "ML-DSA-65": 0,
     Dilithium3: 0,
-    MlDsa65: 1,
+    MlDsa65: 0,
     SphincsSha2256f: 2,
 };
 /**
@@ -30,11 +32,13 @@ export const SIGNATURE_TYPE_IDS = {
  * corresponding {@link SignatureTypeName}.
  *
  * Keys are lowercase; matching is done after calling `.toLowerCase()`.
+ * Always returns the FIPS 204 canonical name `"ML-DSA-65"` for ML-DSA-65 variants.
  */
 export const KEY_TYPE_TO_SIGNATURE_TYPE = {
-    dilithium3: "Dilithium3",
+    "ml-dsa-65": "ML-DSA-65",
+    mldsa65: "ML-DSA-65",
+    dilithium3: "ML-DSA-65",
     "sphincs-sha2-256f": "SphincsSha2256f",
-    mldsa65: "MlDsa65",
 };
 /**
  * High-level Shell Chain signer.
@@ -131,6 +135,7 @@ export class ShellSigner {
             signature,
             signatureType: this.signatureType,
             senderPubkey: options.includePublicKey ? this.getPublicKey() : undefined,
+            aaBbundle: options.aaBundle,
         });
     }
 }

package/dist/transactions.d.ts

@@ -1,4 +1,6 @@
-import type { AddressLike, HexString, ShellSignature, ShellTransactionRequest, SignedShellTransaction, SignatureTypeName } from "./types.js";
+import type { AaBundle, AaInnerCall, AddressLike, HexString, ShellSignature, ShellTransactionRequest, SignedShellTransaction, SignatureTypeName } from "./types.js";
+import { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS } from "./types.js";
+export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS };
 /** Default transaction type: `2` (EIP-1559). */
 export declare const DEFAULT_TX_TYPE = 2;
 /** Default gas limit for simple SHELL token transfers (`21_000`). */
@@ -48,6 +50,8 @@ export interface BuildSignedTransactionOptions {
     signatureType: SignatureTypeName;
     /** Optional public key bytes to embed as `sender_pubkey`. */
     senderPubkey?: Uint8Array | number[];
+    /** AA bundle to attach when `tx.tx_type === AA_BUNDLE_TX_TYPE`. */
+    aaBbundle?: AaBundle;
 }
 /**
  * Low-level transaction builder that maps camelCase options to the
@@ -206,3 +210,127 @@ export declare function hexBytes(bytes: Uint8Array): HexString;
  * @returns 32-byte keccak256 hash as a `Uint8Array`.
  */
 export declare function hashTransaction(tx: ShellTransactionRequest): Uint8Array;
+/**
+ * Options for {@link buildBatchTransaction}.
+ */
+export interface BuildBatchTransactionOptions {
+    /** EIP-155 chain ID. */
+    chainId: number;
+    /** Sender account nonce. */
+    nonce: number;
+    /** Inner calls to include in the batch. Max {@link AA_MAX_INNER_CALLS}. */
+    innerCalls: AaInnerCall[];
+    /**
+     * Total gas budget for the outer transaction.
+     * Should be ≥ sum(innerCalls[i].gas_limit) + 21 000 + overhead.
+     * Defaults to `200_000`.
+     */
+    gasLimit?: number;
+    /** EIP-1559 max fee per gas. Defaults to {@link DEFAULT_MAX_FEE_PER_GAS}. */
+    maxFeePerGas?: number;
+    /** EIP-1559 priority fee. Defaults to {@link DEFAULT_MAX_PRIORITY_FEE_PER_GAS}. */
+    maxPriorityFeePerGas?: number;
+}
+/**
+ * Options for {@link buildSponsoredTransaction}.
+ *
+ * Extends {@link BuildBatchTransactionOptions} with paymaster fields.
+ */
+export interface BuildSponsoredTransactionOptions extends BuildBatchTransactionOptions {
+    /** Paymaster address that will pay the gas cost. */
+    paymaster: AddressLike;
+    /**
+     * Paymaster's PQ signature over the `paymaster_signing_hash`.
+     * Obtain this from the paymaster service before building the transaction.
+     */
+    paymasterSignature: Uint8Array | number[];
+}
+/** Default outer gas budget for AA batch transactions. */
+export declare const DEFAULT_AA_GAS_LIMIT = 200000;
+/**
+ * Build a native AA batch transaction (`tx_type = 0x7E`).
+ *
+ * The resulting `SignedShellTransaction` will have `aa_bundle` set.
+ * The caller is responsible for signing the `batch_signing_hash` (use
+ * {@link hashBatchTransaction}) rather than the plain `tx.hash()`.
+ *
+ * @param options - Batch transaction options including inner calls.
+ * @returns `{ tx: ShellTransactionRequest; aa_bundle: AaBundle }` — an unsigned transaction
+ *   skeleton plus bundle. Pass `txHash: hashBatchTransaction(tx, aa_bundle)` and `aa_bundle`
+ *   into `signer.buildSignedTransaction(...)` to produce the final signed transaction.
+ *
+ * @example
+ * ```typescript
+ * import { buildBatchTransaction, hashBatchTransaction } from "shell-sdk/transactions";
+ *
+ * const { tx, aa_bundle } = buildBatchTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [{ to: "pq1recipient…", value: "0x3e8", data: "0x", gas_limit: 21_000 }],
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash: signingHash, aaBundle: aa_bundle });
+ * ```
+ */
+export declare function buildBatchTransaction(options: BuildBatchTransactionOptions): {
+    tx: ShellTransactionRequest;
+    aa_bundle: AaBundle;
+};
+/**
+ * Build a sponsored AA batch transaction (`tx_type = 0x7E`) with a paymaster.
+ *
+ * Identical to {@link buildBatchTransaction} but also sets `paymaster` and
+ * `paymaster_signature` in the bundle.
+ *
+ * @param options - Sponsored transaction options including paymaster address and signature.
+ * @returns An unsigned `SignedShellTransaction` skeleton plus the bundle.
+ *
+ * @example
+ * ```typescript
+ * const { tx, aa_bundle } = buildSponsoredTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [...],
+ *   paymaster: "pq1paymaster…",
+ *   paymasterSignature: pmSigBytes,
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash: signingHash, aaBundle: aa_bundle });
+ * ```
+ */
+export declare function buildSponsoredTransaction(options: BuildSponsoredTransactionOptions): {
+    tx: ShellTransactionRequest;
+    aa_bundle: AaBundle;
+};
+/**
+ * Compute the `batch_signing_hash` for an AA bundle transaction.
+ *
+ * This is the hash that the **sender** must sign (not the plain `tx.hash()`).
+ * The domain separation prevents replay attacks across tx types.
+ *
+ * Domain: `keccak256( 0x42 || RLP(tx) || RLP(aa_bundle_signing_fields) )`
+ *
+ * @param tx - The outer unsigned transaction (must have `tx_type = 0x7E`).
+ * @param bundle - The AA bundle that will be attached.
+ * @returns 32-byte keccak256 hash as a `Uint8Array`.
+ */
+export declare function hashBatchTransaction(tx: ShellTransactionRequest, bundle: AaBundle): Uint8Array;
+/**
+ * Convenience helper: build a minimal `AaInnerCall` for a SHELL token transfer.
+ *
+ * @param to - Recipient address.
+ * @param value - Amount in wei to send.
+ * @param gasLimit - Gas limit for this inner call. Defaults to `21_000`.
+ * @returns An `AaInnerCall` ready for use in {@link buildBatchTransaction}.
+ */
+export declare function buildInnerTransfer(to: AddressLike, value: bigint, gasLimit?: number): AaInnerCall;
+/**
+ * Convenience helper: build a contract-call `AaInnerCall`.
+ *
+ * @param to - Target contract address.
+ * @param data - ABI-encoded calldata.
+ * @param gasLimit - Gas limit for this inner call.
+ * @param value - Optional ETH value. Defaults to `0n`.
+ * @returns An `AaInnerCall` ready for use in {@link buildBatchTransaction}.
+ */
+export declare function buildInnerCall(to: AddressLike, data: HexString, gasLimit: number, value?: bigint): AaInnerCall;

package/dist/transactions.js

@@ -3,11 +3,13 @@
  *
  * Provides typed helpers for constructing `ShellTransactionRequest` objects
  * for common operations: token transfers, system contract calls, key rotation,
- * and custom validation code management.
+ * custom validation code management, and AA batch/sponsored transactions.
  *
  * @module transactions
  */
 import { bytesToHex, keccak256, toRlp, hexToBytes } from "viem";
+import { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS } from "./types.js";
+export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS };
 import { accountManagerAddress, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, } from "./system-contracts.js";
 import { normalizeHexAddress } from "./address.js";
 /** Default transaction type: `2` (EIP-1559). */
@@ -208,6 +210,7 @@ export function buildSignedTransaction(options) {
         tx: options.tx,
         signature: buildSignature(options.signatureType, options.signature),
         sender_pubkey: options.senderPubkey ? toByteArray(options.senderPubkey) : null,
+        aa_bundle: options.aaBbundle ?? null,
     };
 }
 /**
@@ -262,3 +265,163 @@ export function hashTransaction(tx) {
     const hash = hexToBytes(keccak256(rlpEncoded));
     return hash;
 }
+// ---------------------------------------------------------------------------
+// AA batch & sponsored transaction builders (v0.18.0)
+// ---------------------------------------------------------------------------
+/** `keccak256` domain prefix byte for the batch signing hash (must match chain). */
+const BATCH_SIGNING_HASH_DOMAIN = 0x42;
+/** Default outer gas budget for AA batch transactions. */
+export const DEFAULT_AA_GAS_LIMIT = 200_000;
+/**
+ * Build a native AA batch transaction (`tx_type = 0x7E`).
+ *
+ * The resulting `SignedShellTransaction` will have `aa_bundle` set.
+ * The caller is responsible for signing the `batch_signing_hash` (use
+ * {@link hashBatchTransaction}) rather than the plain `tx.hash()`.
+ *
+ * @param options - Batch transaction options including inner calls.
+ * @returns `{ tx: ShellTransactionRequest; aa_bundle: AaBundle }` — an unsigned transaction
+ *   skeleton plus bundle. Pass `txHash: hashBatchTransaction(tx, aa_bundle)` and `aa_bundle`
+ *   into `signer.buildSignedTransaction(...)` to produce the final signed transaction.
+ *
+ * @example
+ * ```typescript
+ * import { buildBatchTransaction, hashBatchTransaction } from "shell-sdk/transactions";
+ *
+ * const { tx, aa_bundle } = buildBatchTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [{ to: "pq1recipient…", value: "0x3e8", data: "0x", gas_limit: 21_000 }],
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash: signingHash, aaBundle: aa_bundle });
+ * ```
+ */
+export function buildBatchTransaction(options) {
+    if (options.innerCalls.length === 0) {
+        throw new Error("buildBatchTransaction: innerCalls must not be empty");
+    }
+    if (options.innerCalls.length > AA_MAX_INNER_CALLS) {
+        throw new Error(`buildBatchTransaction: innerCalls length ${options.innerCalls.length} exceeds AA_MAX_INNER_CALLS (${AA_MAX_INNER_CALLS})`);
+    }
+    const tx = buildTransaction({
+        chainId: options.chainId,
+        nonce: options.nonce,
+        to: null,
+        value: 0n,
+        data: "0x",
+        gasLimit: options.gasLimit ?? DEFAULT_AA_GAS_LIMIT,
+        maxFeePerGas: options.maxFeePerGas ?? DEFAULT_MAX_FEE_PER_GAS,
+        maxPriorityFeePerGas: options.maxPriorityFeePerGas ?? DEFAULT_MAX_PRIORITY_FEE_PER_GAS,
+        txType: AA_BUNDLE_TX_TYPE,
+    });
+    const aa_bundle = {
+        inner_calls: options.innerCalls,
+        paymaster: null,
+        paymaster_signature: null,
+    };
+    return { tx, aa_bundle };
+}
+/**
+ * Build a sponsored AA batch transaction (`tx_type = 0x7E`) with a paymaster.
+ *
+ * Identical to {@link buildBatchTransaction} but also sets `paymaster` and
+ * `paymaster_signature` in the bundle.
+ *
+ * @param options - Sponsored transaction options including paymaster address and signature.
+ * @returns An unsigned `SignedShellTransaction` skeleton plus the bundle.
+ *
+ * @example
+ * ```typescript
+ * const { tx, aa_bundle } = buildSponsoredTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [...],
+ *   paymaster: "pq1paymaster…",
+ *   paymasterSignature: pmSigBytes,
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash: signingHash, aaBundle: aa_bundle });
+ * ```
+ */
+export function buildSponsoredTransaction(options) {
+    const { tx, aa_bundle } = buildBatchTransaction(options);
+    aa_bundle.paymaster = options.paymaster;
+    aa_bundle.paymaster_signature = Array.from(options.paymasterSignature);
+    return { tx, aa_bundle };
+}
+/**
+ * Compute the `batch_signing_hash` for an AA bundle transaction.
+ *
+ * This is the hash that the **sender** must sign (not the plain `tx.hash()`).
+ * The domain separation prevents replay attacks across tx types.
+ *
+ * Domain: `keccak256( 0x42 || RLP(tx) || RLP(aa_bundle_signing_fields) )`
+ *
+ * @param tx - The outer unsigned transaction (must have `tx_type = 0x7E`).
+ * @param bundle - The AA bundle that will be attached.
+ * @returns 32-byte keccak256 hash as a `Uint8Array`.
+ */
+export function hashBatchTransaction(tx, bundle) {
+    if (tx.tx_type !== AA_BUNDLE_TX_TYPE) {
+        throw new Error(`hashBatchTransaction: tx.tx_type must be AA_BUNDLE_TX_TYPE (0x7E), got ${tx.tx_type}`);
+    }
+    // Encode inner calls for signing (matches chain's encode_for_signing).
+    const innerCallsRlp = bundle.inner_calls.map((call) => [
+        call.to ? normalizeHexAddress(call.to) : "0x",
+        toRlpUint(call.value),
+        call.data,
+        toRlpUint(call.gas_limit),
+    ]);
+    // Paymaster: 20-byte address or empty bytes.
+    const paymasterField = bundle.paymaster
+        ? normalizeHexAddress(bundle.paymaster)
+        : "0x";
+    const txFields = [
+        toRlpUint(tx.chain_id),
+        toRlpUint(tx.nonce),
+        tx.to ? normalizeHexAddress(tx.to) : "0x",
+        toRlpUint(tx.value),
+        tx.data,
+        toRlpUint(tx.gas_limit),
+        toRlpUint(tx.max_fee_per_gas),
+        toRlpUint(tx.max_priority_fee_per_gas),
+        toRlpAccessList(tx.access_list),
+        toRlpUint(tx.tx_type ?? AA_BUNDLE_TX_TYPE),
+        toRlpUint(tx.max_fee_per_blob_gas != null ? 1 : 0),
+        toRlpUint(tx.max_fee_per_blob_gas ?? 0),
+        (tx.blob_versioned_hashes ?? []).map((hash) => hash),
+    ];
+    const bundleSigningFields = [innerCallsRlp, paymasterField];
+    const domainBuf = new Uint8Array([BATCH_SIGNING_HASH_DOMAIN]);
+    const txRlp = hexToBytes(toRlp(txFields));
+    const bundleRlp = hexToBytes(toRlp(bundleSigningFields));
+    const combined = new Uint8Array(domainBuf.length + txRlp.length + bundleRlp.length);
+    combined.set(domainBuf, 0);
+    combined.set(txRlp, domainBuf.length);
+    combined.set(bundleRlp, domainBuf.length + txRlp.length);
+    return hexToBytes(keccak256(bytesToHex(combined)));
+}
+/**
+ * Convenience helper: build a minimal `AaInnerCall` for a SHELL token transfer.
+ *
+ * @param to - Recipient address.
+ * @param value - Amount in wei to send.
+ * @param gasLimit - Gas limit for this inner call. Defaults to `21_000`.
+ * @returns An `AaInnerCall` ready for use in {@link buildBatchTransaction}.
+ */
+export function buildInnerTransfer(to, value, gasLimit = 21_000) {
+    return { to, value: ("0x" + value.toString(16)), data: "0x", gas_limit: gasLimit };
+}
+/**
+ * Convenience helper: build a contract-call `AaInnerCall`.
+ *
+ * @param to - Target contract address.
+ * @param data - ABI-encoded calldata.
+ * @param gasLimit - Gas limit for this inner call.
+ * @param value - Optional ETH value. Defaults to `0n`.
+ * @returns An `AaInnerCall` ready for use in {@link buildBatchTransaction}.
+ */
+export function buildInnerCall(to, data, gasLimit, value = 0n) {
+    return { to, value: ("0x" + value.toString(16)), data, gas_limit: gasLimit };
+}

package/dist/types.d.ts

@@ -32,7 +32,7 @@ export interface ShellTransactionRequest {
     max_priority_fee_per_gas: number;
     /** Optional EIP-2930 access list. */
     access_list?: ShellAccessListItem[] | null;
-    /** Transaction type; defaults to `2` (EIP-1559). */
+    /** Transaction type; defaults to `2` (EIP-1559). AA bundle uses `0x7E`. */
     tx_type?: number;
     /** EIP-4844 max fee per blob gas unit. */
     max_fee_per_blob_gas?: number | null;
@@ -42,11 +42,12 @@ export interface ShellTransactionRequest {
 /**
  * The name of a supported post-quantum signature algorithm.
  *
- * - `"Dilithium3"` — Round-3 Dilithium (algorithm ID 0); uses the ML-DSA-65 implementation as a stand-in.
- * - `"MlDsa65"` — NIST FIPS 204 ML-DSA-65 (algorithm ID 1).
+ * - `"ML-DSA-65"` — NIST FIPS 204 ML-DSA-65 (canonical name, algorithm ID 0); preferred.
+ * - `"Dilithium3"` — Compatibility alias for `"ML-DSA-65"` (same wire format, algorithm ID 0).
+ * - `"MlDsa65"` — Legacy camelCase alias for `"ML-DSA-65"` (algorithm ID 0); still accepted.
  * - `"SphincsSha2256f"` — NIST FIPS 205 SLH-DSA-SHA2-256f (algorithm ID 2).
  */
-export type SignatureTypeName = "Dilithium3" | "MlDsa65" | "SphincsSha2256f";
+export type SignatureTypeName = "ML-DSA-65" | "Dilithium3" | "MlDsa65" | "SphincsSha2256f";
 /**
  * A post-quantum signature attached to a transaction.
  *
@@ -59,6 +60,51 @@ export interface ShellSignature {
     /** Raw signature bytes as a JS number array. */
     data: number[];
 }
+/**
+ * Transaction type byte for AA bundle transactions.
+ *
+ * `0x7E` — carries a {@link AaBundle} with N inner calls and an optional paymaster.
+ */
+export declare const AA_BUNDLE_TX_TYPE = 126;
+/**
+ * Maximum number of inner calls per AA bundle.
+ */
+export declare const AA_MAX_INNER_CALLS = 16;
+/**
+ * A single call within an AA batch bundle.
+ *
+ * Mirrors `InnerCall` on the chain side.
+ */
+export interface AaInnerCall {
+    /** Recipient address, or `null` for contract creation. */
+    to: AddressLike | null;
+    /** Value in wei as a hex string (e.g. `"0x0"`, `"0xde0b6b3a7640000"`). JSON-safe. */
+    value: HexString;
+    /** ABI-encoded calldata. */
+    data: HexString;
+    /** Gas limit for this inner call. */
+    gas_limit: number;
+}
+/**
+ * The AA bundle payload attached to a `tx_type = 0x7E` transaction.
+ *
+ * All inner calls execute atomically under a single PQ signature covering
+ * the outer envelope + bundle (via `batch_signing_hash`).
+ */
+export interface AaBundle {
+    /** Ordered list of inner calls to execute. Max {@link AA_MAX_INNER_CALLS}. */
+    inner_calls: AaInnerCall[];
+    /**
+     * Optional paymaster address paying the gas cost.
+     * When set, `paymaster_signature` must also be provided.
+     */
+    paymaster?: AddressLike | null;
+    /**
+     * Paymaster's PQ signature over the `paymaster_signing_hash`.
+     * Required when `paymaster` is set.
+     */
+    paymaster_signature?: number[] | null;
+}
 /**
  * A fully-signed Shell Chain transaction ready to broadcast via `shell_sendTransaction`.
  *
@@ -81,6 +127,109 @@ export interface SignedShellTransaction {
      * verify the address derivation. Pass `null` for subsequent transactions.
      */
     sender_pubkey?: number[] | null;
+    /**
+     * AA bundle payload. Present only when `tx.tx_type === AA_BUNDLE_TX_TYPE`.
+     */
+    aa_bundle?: AaBundle | null;
+}
+/**
+ * A single inner call entry in a `shell_estimateBatch` request.
+ */
+export interface ShellBatchInnerCallRequest {
+    /** Recipient address, or `null`. */
+    to?: AddressLike | null;
+    /** Value as hex string (e.g. `"0x0"`). */
+    value?: string | null;
+    /** ABI-encoded calldata. */
+    data?: HexString | null;
+    /** Gas limit as hex string. If absent, the node simulates to estimate. */
+    gas_limit?: string | null;
+}
+/**
+ * Request body for `shell_estimateBatch`.
+ */
+export interface ShellEstimateBatchRequest {
+    /** Nominal sender address for simulation. Defaults to zero address. */
+    from?: AddressLike | null;
+    /** Optional paymaster (informational; does not affect gas estimate). */
+    paymaster?: AddressLike | null;
+    /** Inner calls to estimate. */
+    inner_calls: ShellBatchInnerCallRequest[];
+}
+/**
+ * Per-inner-call estimate entry returned by `shell_estimateBatch`.
+ */
+export interface ShellBatchInnerGas {
+    /** Gas limit as hex string. */
+    gas_limit: string;
+    /** `true` if the node simulated this call (no `gas_limit` was provided). */
+    simulated: boolean;
+}
+/**
+ * Response from `shell_estimateBatch`.
+ */
+export interface ShellEstimateBatchResult {
+    /** Total gas (outer intrinsic + inner sum + surcharge) as hex string. */
+    total_gas: string;
+    /** Outer transaction intrinsic gas (always `"0x5208"` = 21 000). */
+    outer_intrinsic: string;
+    /** Sum of all inner gas limits as hex string. */
+    inner_sum: string;
+    /** Per-extra-inner-call intrinsic surcharge as hex string. */
+    intrinsic_surcharge: string;
+    /** Per-inner gas estimates. */
+    per_inner: ShellBatchInnerGas[];
+    /** Paymaster echoed back (if supplied in request). */
+    paymaster?: AddressLike | null;
+}
+/**
+ * Paymaster policy returned by `shell_getPaymasterPolicy`.
+ */
+export interface ShellPaymasterPolicy {
+    /** Paymaster address (pq1… form). */
+    address: AddressLike;
+    /** `true` if a PQ pubkey has been registered on-chain for this address. */
+    has_pq_pubkey: boolean;
+    /** Pubkey byte length (if present). */
+    pubkey_bytes?: number | null;
+    /** SHELL balance of the paymaster as hex string. */
+    balance: string;
+    /** Policy type; currently always `"eoa-open"`. */
+    policy: string;
+    /** Maximum gas sponsorship cap (null = uncapped). */
+    max_gas_sponsorship?: string | null;
+}
+/**
+ * Response from `shell_isSponsored`.
+ */
+export interface ShellIsSponsoredResult {
+    /** `true` if the transaction was found (mempool or chain). */
+    found: boolean;
+    /** `true` if the transaction is sponsored by a paymaster. */
+    sponsored: boolean;
+    /** Where the transaction was found: `"mempool"`, `"chain"`, or `null`. */
+    location: "mempool" | "chain" | null;
+    /** `true` if the transaction is a native AA bundle. */
+    is_aa_bundle: boolean;
+    /** Paymaster address, or `null` if not sponsored. */
+    paymaster: AddressLike | null;
+    /** Sender address. */
+    sender: AddressLike | null;
+    /** Number of inner calls in the bundle, or `null` for non-AA txs. */
+    inner_call_count: number | null;
+}
+/**
+ * Result returned by `shell_verifyWitnessRoot`.
+ */
+export interface ShellWitnessRootResult {
+    /** The block number that was verified (as hex string). */
+    block: string;
+    /** The witness root stored in the block header (hex). */
+    witness_root: string;
+    /** The recomputed root from the bundle signatures (hex). */
+    bundle_root: string;
+    /** `true` if `witness_root === bundle_root`. */
+    match: boolean;
 }
 /**
  * Node storage profile as advertised via the `StorageCapability` P2P message.
@@ -96,7 +245,7 @@ export type ShellStorageProfile = "archive" | "full" | "light";
  * Contains runtime metadata about the connected Shell Chain node.
  */
 export interface ShellNodeInfo {
-    /** Node software version string, e.g. `"shell-node/0.17.0"`, independent of the SDK package version. */
+    /** Node software version string, e.g. `"shell-node/0.18.0"`. */
     version: string;
     /** Chain ID as a decimal string. */
     chain_id: string;
@@ -136,6 +285,11 @@ export interface ShellWitnessBundle {
     witness_count: number;
     /** Individual transaction witnesses. */
     witnesses: ShellTxWitness[];
+    /**
+     * Merkle root of the witness bundle (stored in the block header).
+     * Present on archive/full nodes.
+     */
+    witness_root?: string;
 }
 /** Paginated response from `shell_getTransactionsByAddress`. */
 export interface ShellTxByAddressPage {

package/dist/types.js

@@ -1 +1,13 @@
-export {};
+// ---------------------------------------------------------------------------
+// Native AA types (v0.18.0)
+// ---------------------------------------------------------------------------
+/**
+ * Transaction type byte for AA bundle transactions.
+ *
+ * `0x7E` — carries a {@link AaBundle} with N inner calls and an optional paymaster.
+ */
+export const AA_BUNDLE_TX_TYPE = 0x7e;
+/**
+ * Maximum number of inner calls per AA bundle.
+ */
+export const AA_MAX_INNER_CALLS = 16;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shell-sdk",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "TypeScript SDK for Shell Chain — build quantum-safe dApps before Q-Day.",
   "license": "MIT",
   "type": "module",