shell-sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.5.0] — 2026-04-26
+
+### Added — AA Phase 2 (matches `shell-chain v0.19.0`)
+
+#### Types (`types.ts`)
+- **`SessionAuth`** interface: session PQ key authorization struct with `session_pubkey`, `session_algo`, `target?`, `value_cap`, `expiry_block`, `root_signature`, `session_signature`.
+- **`GuardianConfig`** interface: on-chain guardian set descriptor.
+- **`RecoveryProposal`** interface: active recovery proposal with votes and maturity block.
+- **`AaBundle`** extended: added `paymaster_context?: number[] | null` (contract paymaster opaque bytes) and `session_auth?: SessionAuth | null` (session key authorization).
+- Constants: `AA_MAX_PAYMASTER_CONTEXT = 256`, `AA_SESSION_KEY_GAS_SURCHARGE = 20_000`.
+
+#### Transaction builders (`transactions.ts`)
+- **`buildContractPaymasterTransaction`**: builds an AA batch tx with a contract paymaster (sets `paymaster_context`). Mutually exclusive with `paymaster_signature`.
+- **`buildSessionKeyTransaction`**: builds an AA batch tx authorized by a session key (sets `session_auth`).
+- **`hashBatchTransaction`**: updated signing hash to include `paymaster_context` as the 3rd RLP field in `bundleSigningFields`, matching `shell-chain` `AaBundle::encode_for_signing`.
+
+#### System contract calldata (`system-contracts.ts`)
+- **`setGuardiansSelector`** + **`encodeSetGuardiansCalldata`**: `setGuardians(address[],uint8,uint64)`.
+- **`submitRecoverySelector`** + **`encodeSubmitRecoveryCalldata`**: `submitRecovery(address,bytes,uint8)`.
+- **`executeRecoverySelector`** + **`encodeExecuteRecoveryCalldata`**: `executeRecovery(address)`.
+- **`cancelRecoverySelector`** + **`encodeCancelRecoveryCalldata`**: `cancelRecovery(address)`.
+
+### Compatibility
+- Fully backwards-compatible with SDK `0.4.x` usage. All new fields are optional.
+- New AA Phase 2 features require `shell-chain v0.19.0+`.
+
+## [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

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 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 { 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 { accountManagerAddress, accountManagerHexAddress, cancelRecoverySelector, clearValidationCodeSelector, encodeCancelRecoveryCalldata, encodeClearValidationCodeCalldata, encodeExecuteRecoveryCalldata, encodeRotateKeyCalldata, encodeSetGuardiansCalldata, encodeSetValidationCodeCalldata, encodeSubmitRecoveryCalldata, executeRecoverySelector, isSystemContractAddress, rotateKeySelector, setGuardiansSelector, setValidationCodeSelector, submitRecoverySelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
+export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS, buildBatchTransaction, buildClearValidationCodeTransaction, buildContractPaymasterTransaction, buildInnerCall, buildInnerTransfer, buildRotateKeyTransaction, buildSessionKeyTransaction, 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 BuildContractPaymasterTransactionOptions, type BuildSessionKeyTransactionOptions, 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 { 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";
+export { AA_MAX_PAYMASTER_CONTEXT, AA_SESSION_KEY_GAS_SURCHARGE } from "./types.js";
+export type { AaBundle, AaInnerCall, AddressLike, GuardianConfig, HexString, RecoveryProposal, SessionAuth, 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,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, } from "./provider.js";
-export { accountManagerAddress, accountManagerHexAddress, clearValidationCodeSelector, encodeClearValidationCodeCalldata, encodeRotateKeyCalldata, encodeSetValidationCodeCalldata, isSystemContractAddress, rotateKeySelector, setValidationCodeSelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.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 { accountManagerAddress, accountManagerHexAddress, cancelRecoverySelector, clearValidationCodeSelector, encodeCancelRecoveryCalldata, encodeClearValidationCodeCalldata, encodeExecuteRecoveryCalldata, encodeRotateKeyCalldata, encodeSetGuardiansCalldata, encodeSetValidationCodeCalldata, encodeSubmitRecoveryCalldata, executeRecoverySelector, isSystemContractAddress, rotateKeySelector, setGuardiansSelector, setValidationCodeSelector, submitRecoverySelector, validatorRegistryAddress, validatorRegistryHexAddress, } from "./system-contracts.js";
+export { AA_BUNDLE_TX_TYPE, AA_MAX_INNER_CALLS, buildBatchTransaction, buildClearValidationCodeTransaction, buildContractPaymasterTransaction, buildInnerCall, buildInnerTransfer, buildRotateKeyTransaction, buildSessionKeyTransaction, 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";
+export { AA_MAX_PAYMASTER_CONTEXT, AA_SESSION_KEY_GAS_SURCHARGE } from "./types.js";

package/dist/provider.d.ts

@@ -189,14 +189,14 @@ export declare class ShellProvider {
      * Calls `shell_estimateBatch`.
      *
      * @param request - Batch estimate request with inner calls and optional paymaster.
-     * @returns Gas estimates including `totalGas`, `perInner`, and breakdown fields.
+     * @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.totalGas, 16);
+     * const totalGas = parseInt(estimate.total_gas, 16);
      * ```
      */
     estimateBatch(request: ShellEstimateBatchRequest): Promise<ShellEstimateBatchResult>;

package/dist/provider.js

@@ -179,14 +179,14 @@ export class ShellProvider {
      * Calls `shell_estimateBatch`.
      *
      * @param request - Batch estimate request with inner calls and optional paymaster.
-     * @returns Gas estimates including `totalGas`, `perInner`, and breakdown fields.
+     * @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.totalGas, 16);
+     * const totalGas = parseInt(estimate.total_gas, 16);
      * ```
      */
     async estimateBatch(request) {

package/dist/system-contracts.d.ts

@@ -13,6 +13,14 @@ export declare const rotateKeySelector: `0x${string}`;
 export declare const setValidationCodeSelector: `0x${string}`;
 /** 4-byte ABI function selector for `clearValidationCode()`. */
 export declare const clearValidationCodeSelector: `0x${string}`;
+/** 4-byte ABI function selector for `setGuardians(address[],uint8,uint64)`. */
+export declare const setGuardiansSelector: `0x${string}`;
+/** 4-byte ABI function selector for `submitRecovery(address,bytes,uint8)`. */
+export declare const submitRecoverySelector: `0x${string}`;
+/** 4-byte ABI function selector for `executeRecovery(address)`. */
+export declare const executeRecoverySelector: `0x${string}`;
+/** 4-byte ABI function selector for `cancelRecovery(address)`. */
+export declare const cancelRecoverySelector: `0x${string}`;
 /**
  * ABI-encode calldata for `rotateKey(bytes publicKey, uint8 algorithmId)`.
  *
@@ -63,3 +71,67 @@ export declare function encodeClearValidationCodeCalldata(): HexString;
  * ```
  */
 export declare function isSystemContractAddress(address: AddressLike): boolean;
+/**
+ * ABI-encode calldata for `setGuardians(address[] guardians, uint8 threshold, uint64 timelock)`.
+ *
+ * Configures the guardian recovery set for the caller's account. Only the
+ * account owner can call this (the call must be made as an inner call from
+ * the owner's AA bundle, or as a direct transaction).
+ *
+ * @param guardians - Array of guardian addresses (1..5). May be hex or `pq1…` form.
+ * @param threshold - k-of-n required votes (1 ≤ threshold ≤ guardians.length).
+ * @param timelock - Minimum blocks between threshold-reach and execution (≥ 100).
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeSetGuardiansCalldata(
+ *   ["0xGuardian1…", "0xGuardian2…", "0xGuardian3…"],
+ *   2,   // 2-of-3 threshold
+ *   100, // 100-block timelock
+ * );
+ * ```
+ */
+export declare function encodeSetGuardiansCalldata(guardians: AddressLike[], threshold: number, timelock: number): HexString;
+/**
+ * ABI-encode calldata for `submitRecovery(address account, bytes newPubkey, uint8 newAlgo)`.
+ *
+ * Called by a guardian to vote for a new PQ public key on behalf of `account`.
+ * When k-of-n threshold is reached, the proposal becomes executable after
+ * `timelock` blocks.
+ *
+ * @param account - Account being recovered (0x hex or `pq1…` form).
+ * @param newPubkey - Raw bytes of the new PQ public key.
+ * @param newAlgo - Algorithm ID for the new key (ML-DSA-65 = 0, etc.).
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeSubmitRecoveryCalldata(
+ *   "0xAccountAddress…",
+ *   newPubkeyBytes,
+ *   0, // ML-DSA-65
+ * );
+ * ```
+ */
+export declare function encodeSubmitRecoveryCalldata(account: AddressLike, newPubkey: Uint8Array, newAlgo: number): HexString;
+/**
+ * ABI-encode calldata for `executeRecovery(address account)`.
+ *
+ * Can be called by anyone once the recovery proposal has reached maturity
+ * (`current_block >= maturity_block && maturity_block != 0`).
+ *
+ * @param account - Account whose recovery proposal to execute.
+ * @returns `HexString` with the 4-byte selector prepended.
+ */
+export declare function encodeExecuteRecoveryCalldata(account: AddressLike): HexString;
+/**
+ * ABI-encode calldata for `cancelRecovery(address account)`.
+ *
+ * Owner-only: removes the active recovery proposal. Useful if the account
+ * owner regains access before the timelock expires.
+ *
+ * @param account - Account whose recovery proposal to cancel (must be caller).
+ * @returns `HexString` with the 4-byte selector prepended.
+ */
+export declare function encodeCancelRecoveryCalldata(account: AddressLike): HexString;

package/dist/system-contracts.js

@@ -4,12 +4,17 @@
  * Shell Chain ships two built-in system contracts at well-known addresses:
  *
  * - **ValidatorRegistry** (`0x…0001`) — manages the set of active validators.
- * - **AccountManager** (`0x…0002`) — handles per-account key rotation and
- *   custom AA validation code.
+ * - **AccountManager** (`0x…0002`) — handles per-account key rotation,
+ *   custom AA validation code, and (v0.19.0+) guardian recovery.
  *
  * Transactions targeting these contracts should be built with the helpers in
  * `transactions.ts` (e.g. {@link buildRotateKeyTransaction}).
  *
+ * ## AA Phase 2 — Guardian Recovery (v0.19.0-dev)
+ *
+ * Use {@link encodeSetGuardiansCalldata}, {@link encodeSubmitRecoveryCalldata},
+ * {@link encodeExecuteRecoveryCalldata}, and {@link encodeCancelRecoveryCalldata}.
+ *
  * @module system-contracts
  */
 import { bytesToHex, encodeAbiParameters, keccak256, toBytes } from "viem";
@@ -37,6 +42,17 @@ export const rotateKeySelector = selector("rotateKey(bytes,uint8)");
 export const setValidationCodeSelector = selector("setValidationCode(bytes32)");
 /** 4-byte ABI function selector for `clearValidationCode()`. */
 export const clearValidationCodeSelector = selector("clearValidationCode()");
+// ---------------------------------------------------------------------------
+// AA Phase 2 — Guardian Recovery selectors (v0.19.0-dev)
+// ---------------------------------------------------------------------------
+/** 4-byte ABI function selector for `setGuardians(address[],uint8,uint64)`. */
+export const setGuardiansSelector = selector("setGuardians(address[],uint8,uint64)");
+/** 4-byte ABI function selector for `submitRecovery(address,bytes,uint8)`. */
+export const submitRecoverySelector = selector("submitRecovery(address,bytes,uint8)");
+/** 4-byte ABI function selector for `executeRecovery(address)`. */
+export const executeRecoverySelector = selector("executeRecovery(address)");
+/** 4-byte ABI function selector for `cancelRecovery(address)`. */
+export const cancelRecoverySelector = selector("cancelRecovery(address)");
 /**
  * ABI-encode calldata for `rotateKey(bytes publicKey, uint8 algorithmId)`.
  *
@@ -103,3 +119,99 @@ export function isSystemContractAddress(address) {
         address === accountManagerHexAddress ||
         address === validatorRegistryHexAddress);
 }
+// ---------------------------------------------------------------------------
+// AA Phase 2 — Guardian Recovery calldata encoders (v0.19.0-dev)
+// ---------------------------------------------------------------------------
+/**
+ * ABI-encode calldata for `setGuardians(address[] guardians, uint8 threshold, uint64 timelock)`.
+ *
+ * Configures the guardian recovery set for the caller's account. Only the
+ * account owner can call this (the call must be made as an inner call from
+ * the owner's AA bundle, or as a direct transaction).
+ *
+ * @param guardians - Array of guardian addresses (1..5). May be hex or `pq1…` form.
+ * @param threshold - k-of-n required votes (1 ≤ threshold ≤ guardians.length).
+ * @param timelock - Minimum blocks between threshold-reach and execution (≥ 100).
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeSetGuardiansCalldata(
+ *   ["0xGuardian1…", "0xGuardian2…", "0xGuardian3…"],
+ *   2,   // 2-of-3 threshold
+ *   100, // 100-block timelock
+ * );
+ * ```
+ */
+export function encodeSetGuardiansCalldata(guardians, threshold, timelock) {
+    // Normalise to 0x… form; encodeAbiParameters expects `0x${string}` addresses.
+    const hexGuardians = guardians.map((g) => {
+        const s = typeof g === "string" ? g : bytesToHex(g);
+        return (s.startsWith("0x") ? s : `0x${s}`);
+    });
+    const encoded = encodeAbiParameters([{ type: "address[]" }, { type: "uint8" }, { type: "uint64" }], [hexGuardians, threshold, BigInt(timelock)]);
+    return `${setGuardiansSelector}${encoded.slice(2)}`;
+}
+/**
+ * ABI-encode calldata for `submitRecovery(address account, bytes newPubkey, uint8 newAlgo)`.
+ *
+ * Called by a guardian to vote for a new PQ public key on behalf of `account`.
+ * When k-of-n threshold is reached, the proposal becomes executable after
+ * `timelock` blocks.
+ *
+ * @param account - Account being recovered (0x hex or `pq1…` form).
+ * @param newPubkey - Raw bytes of the new PQ public key.
+ * @param newAlgo - Algorithm ID for the new key (ML-DSA-65 = 0, etc.).
+ * @returns `HexString` with the 4-byte selector prepended.
+ *
+ * @example
+ * ```typescript
+ * const data = encodeSubmitRecoveryCalldata(
+ *   "0xAccountAddress…",
+ *   newPubkeyBytes,
+ *   0, // ML-DSA-65
+ * );
+ * ```
+ */
+export function encodeSubmitRecoveryCalldata(account, newPubkey, newAlgo) {
+    const hexAccount = normaliseToHex(account);
+    const encoded = encodeAbiParameters([{ type: "address" }, { type: "bytes" }, { type: "uint8" }], [hexAccount, bytesToHex(newPubkey), newAlgo]);
+    return `${submitRecoverySelector}${encoded.slice(2)}`;
+}
+/**
+ * ABI-encode calldata for `executeRecovery(address account)`.
+ *
+ * Can be called by anyone once the recovery proposal has reached maturity
+ * (`current_block >= maturity_block && maturity_block != 0`).
+ *
+ * @param account - Account whose recovery proposal to execute.
+ * @returns `HexString` with the 4-byte selector prepended.
+ */
+export function encodeExecuteRecoveryCalldata(account) {
+    const hexAccount = normaliseToHex(account);
+    const encoded = encodeAbiParameters([{ type: "address" }], [hexAccount]);
+    return `${executeRecoverySelector}${encoded.slice(2)}`;
+}
+/**
+ * ABI-encode calldata for `cancelRecovery(address account)`.
+ *
+ * Owner-only: removes the active recovery proposal. Useful if the account
+ * owner regains access before the timelock expires.
+ *
+ * @param account - Account whose recovery proposal to cancel (must be caller).
+ * @returns `HexString` with the 4-byte selector prepended.
+ */
+export function encodeCancelRecoveryCalldata(account) {
+    const hexAccount = normaliseToHex(account);
+    const encoded = encodeAbiParameters([{ type: "address" }], [hexAccount]);
+    return `${cancelRecoverySelector}${encoded.slice(2)}`;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function normaliseToHex(address) {
+    if (typeof address !== "string") {
+        return bytesToHex(address);
+    }
+    return (address.startsWith("0x") ? address : `0x${address}`);
+}

package/dist/transactions.d.ts

@@ -1,4 +1,4 @@
-import type { AaBundle, AaInnerCall, AddressLike, HexString, ShellSignature, ShellTransactionRequest, SignedShellTransaction, SignatureTypeName } from "./types.js";
+import type { AaBundle, AaInnerCall, AddressLike, HexString, SessionAuth, 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). */
@@ -334,3 +334,86 @@ export declare function buildInnerTransfer(to: AddressLike, value: bigint, gasLi
  * @returns An `AaInnerCall` ready for use in {@link buildBatchTransaction}.
  */
 export declare function buildInnerCall(to: AddressLike, data: HexString, gasLimit: number, value?: bigint): AaInnerCall;
+/**
+ * Options for {@link buildContractPaymasterTransaction}.
+ *
+ * Extends {@link BuildBatchTransactionOptions} with contract paymaster fields.
+ */
+export interface BuildContractPaymasterTransactionOptions extends BuildBatchTransactionOptions {
+    /** Contract paymaster address. */
+    paymaster: AddressLike;
+    /**
+     * Opaque context bytes forwarded to `IPaymaster.validatePaymasterOp`.
+     * Max 256 bytes.
+     */
+    paymasterContext: Uint8Array | number[];
+}
+/**
+ * Build an AA batch transaction using a **contract paymaster** (Phase 2).
+ *
+ * Unlike {@link buildSponsoredTransaction} (off-chain paymaster), a contract
+ * paymaster implements `IPaymaster.validatePaymasterOp` on-chain and receives
+ * `paymasterContext` as input. The bundle must NOT include `paymaster_signature`.
+ *
+ * @param options - Options including contract paymaster address and context bytes.
+ * @returns `{ tx, aa_bundle }` — an unsigned transaction skeleton plus bundle.
+ *
+ * @example
+ * ```typescript
+ * const { tx, aa_bundle } = buildContractPaymasterTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [...],
+ *   paymaster: contractPaymasterAddress,
+ *   paymasterContext: contextBytes,
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash: signingHash, aaBundle: aa_bundle });
+ * ```
+ */
+export declare function buildContractPaymasterTransaction(options: BuildContractPaymasterTransactionOptions): {
+    tx: ShellTransactionRequest;
+    aa_bundle: AaBundle;
+};
+/**
+ * Options for {@link buildSessionKeyTransaction}.
+ *
+ * Extends {@link BuildBatchTransactionOptions} with session key authorization.
+ */
+export interface BuildSessionKeyTransactionOptions extends BuildBatchTransactionOptions {
+    /** Pre-built session key authorization. */
+    sessionAuth: SessionAuth;
+}
+/**
+ * Build an AA batch transaction authorized by a **session key** (Phase 2).
+ *
+ * The session key must have been authorized by the root account via a
+ * `root_signature` over its `auth_hash`. The transaction is then signed
+ * by the session key via `session_signature`.
+ *
+ * @param options - Options including the session key authorization struct.
+ * @returns `{ tx, aa_bundle }` — an unsigned transaction skeleton plus bundle.
+ *
+ * @example
+ * ```typescript
+ * const { tx, aa_bundle } = buildSessionKeyTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [...],
+ *   sessionAuth: {
+ *     session_pubkey: Array.from(sessionPubkeyBytes),
+ *     session_algo: 0,
+ *     target: null,
+ *     value_cap: "0xde0b6b3a7640000",
+ *     expiry_block: 500,
+ *     root_signature: Array.from(rootSigBytes),
+ *     session_signature: Array.from(sessionSigBytes),
+ *   },
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * ```
+ */
+export declare function buildSessionKeyTransaction(options: BuildSessionKeyTransactionOptions): {
+    tx: ShellTransactionRequest;
+    aa_bundle: AaBundle;
+};

package/dist/transactions.js

@@ -377,6 +377,10 @@ export function hashBatchTransaction(tx, bundle) {
     const paymasterField = bundle.paymaster
         ? normalizeHexAddress(bundle.paymaster)
         : "0x";
+    // paymaster_context: raw bytes or empty.
+    const paymasterContextField = bundle.paymaster_context && bundle.paymaster_context.length > 0
+        ? bytesToHex(new Uint8Array(bundle.paymaster_context))
+        : "0x";
     const txFields = [
         toRlpUint(tx.chain_id),
         toRlpUint(tx.nonce),
@@ -392,7 +396,7 @@ export function hashBatchTransaction(tx, bundle) {
         toRlpUint(tx.max_fee_per_blob_gas ?? 0),
         (tx.blob_versioned_hashes ?? []).map((hash) => hash),
     ];
-    const bundleSigningFields = [innerCallsRlp, paymasterField];
+    const bundleSigningFields = [innerCallsRlp, paymasterField, paymasterContextField];
     const domainBuf = new Uint8Array([BATCH_SIGNING_HASH_DOMAIN]);
     const txRlp = hexToBytes(toRlp(txFields));
     const bundleRlp = hexToBytes(toRlp(bundleSigningFields));
@@ -425,3 +429,66 @@ export function buildInnerTransfer(to, value, gasLimit = 21_000) {
 export function buildInnerCall(to, data, gasLimit, value = 0n) {
     return { to, value: ("0x" + value.toString(16)), data, gas_limit: gasLimit };
 }
+/**
+ * Build an AA batch transaction using a **contract paymaster** (Phase 2).
+ *
+ * Unlike {@link buildSponsoredTransaction} (off-chain paymaster), a contract
+ * paymaster implements `IPaymaster.validatePaymasterOp` on-chain and receives
+ * `paymasterContext` as input. The bundle must NOT include `paymaster_signature`.
+ *
+ * @param options - Options including contract paymaster address and context bytes.
+ * @returns `{ tx, aa_bundle }` — an unsigned transaction skeleton plus bundle.
+ *
+ * @example
+ * ```typescript
+ * const { tx, aa_bundle } = buildContractPaymasterTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [...],
+ *   paymaster: contractPaymasterAddress,
+ *   paymasterContext: contextBytes,
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * const signed = await signer.buildSignedTransaction({ tx, txHash: signingHash, aaBundle: aa_bundle });
+ * ```
+ */
+export function buildContractPaymasterTransaction(options) {
+    const { tx, aa_bundle } = buildBatchTransaction(options);
+    aa_bundle.paymaster = options.paymaster;
+    aa_bundle.paymaster_context = Array.from(options.paymasterContext);
+    return { tx, aa_bundle };
+}
+/**
+ * Build an AA batch transaction authorized by a **session key** (Phase 2).
+ *
+ * The session key must have been authorized by the root account via a
+ * `root_signature` over its `auth_hash`. The transaction is then signed
+ * by the session key via `session_signature`.
+ *
+ * @param options - Options including the session key authorization struct.
+ * @returns `{ tx, aa_bundle }` — an unsigned transaction skeleton plus bundle.
+ *
+ * @example
+ * ```typescript
+ * const { tx, aa_bundle } = buildSessionKeyTransaction({
+ *   chainId: 424242,
+ *   nonce: 0,
+ *   innerCalls: [...],
+ *   sessionAuth: {
+ *     session_pubkey: Array.from(sessionPubkeyBytes),
+ *     session_algo: 0,
+ *     target: null,
+ *     value_cap: "0xde0b6b3a7640000",
+ *     expiry_block: 500,
+ *     root_signature: Array.from(rootSigBytes),
+ *     session_signature: Array.from(sessionSigBytes),
+ *   },
+ * });
+ * const signingHash = hashBatchTransaction(tx, aa_bundle);
+ * ```
+ */
+export function buildSessionKeyTransaction(options) {
+    const { tx, aa_bundle } = buildBatchTransaction(options);
+    aa_bundle.session_auth = options.sessionAuth;
+    return { tx, aa_bundle };
+}

package/dist/types.d.ts

@@ -90,20 +90,125 @@ export interface AaInnerCall {
  *
  * All inner calls execute atomically under a single PQ signature covering
  * the outer envelope + bundle (via `batch_signing_hash`).
+ *
+ * ## AA Phase 2 extensions (v0.19.0-dev)
+ *
+ * - **Contract paymaster** (`paymaster_context`): pass opaque bytes to a
+ *   contract paymaster's `validatePaymasterOp` on-chain. Mutually exclusive
+ *   with `paymaster_signature` (off-chain/EOA paymaster).
+ * - **Session keys** (`session_auth`): attach a short-lived sub-key
+ *   authorization instead of the root PQ key.
  */
 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.
+     *
+     * - EOA/off-chain paymaster: set `paymaster_signature` (not `paymaster_context`).
+     * - Contract paymaster: set `paymaster_context` (not `paymaster_signature`).
      */
     paymaster?: AddressLike | null;
     /**
      * Paymaster's PQ signature over the `paymaster_signing_hash`.
-     * Required when `paymaster` is set.
+     * Required for EOA/off-chain paymaster. Mutually exclusive with `paymaster_context`.
      */
     paymaster_signature?: number[] | null;
+    /**
+     * Opaque context bytes forwarded to `IPaymaster.validatePaymasterOp`.
+     * Required for contract paymaster. Mutually exclusive with `paymaster_signature`.
+     * Max 256 bytes.
+     */
+    paymaster_context?: number[] | null;
+    /**
+     * Session key authorization. When set the root signature field belongs to
+     * the session `root_signature` and `session_signature` pair, not the root
+     * key signing the tx directly.
+     */
+    session_auth?: SessionAuth | null;
+}
+/**
+ * Maximum length of `paymaster_context` bytes (256 bytes).
+ */
+export declare const AA_MAX_PAYMASTER_CONTEXT = 256;
+/**
+ * Extra PQ verify gas cost per session key authorization (2 × PQ_VERIFY_GAS = 20 000).
+ * Added to intrinsic gas when a session key is used.
+ */
+export declare const AA_SESSION_KEY_GAS_SURCHARGE = 20000;
+/**
+ * Session key authorization attached to an AA bundle.
+ *
+ * Allows a short-lived sub-key to authorize a transaction on behalf of the
+ * root account, with optional restrictions on target address and value cap.
+ *
+ * ## Spec (AA_PHASE2_SPEC.md §4)
+ *
+ * 1. `session_pubkey` is authorized by the root key's `root_signature` over
+ *    `auth_hash = blake3(0x81 || session_pubkey || target(20B) || value_cap(32B BE) || expiry_block(8B BE) || chain_id(8B BE))`.
+ * 2. The transaction is signed by `session_pubkey` via `session_signature`.
+ * 3. `expiry_block` must be > current block at validation time.
+ * 4. Σ(inner_call.value) ≤ `value_cap`.
+ * 5. If `target` is set, all inner calls must target that address.
+ *
+ * @example
+ * ```typescript
+ * const sessionAuth: SessionAuth = {
+ *   session_pubkey: Array.from(sessionPubkeyBytes),
+ *   session_algo: 0, // ML-DSA-65
+ *   target: null,
+ *   value_cap: "0xde0b6b3a7640000",
+ *   expiry_block: 500,
+ *   root_signature: Array.from(rootSigBytes),
+ *   session_signature: Array.from(sessionSigBytes),
+ * };
+ * ```
+ */
+export interface SessionAuth {
+    /** Raw bytes of the session public key. */
+    session_pubkey: number[];
+    /** Algorithm ID of the session key (Dilithium3/ML-DSA-65 = 0, SphincsSha2256f = 2). */
+    session_algo: number;
+    /** If set, every inner call in the bundle must target this address. */
+    target?: AddressLike | null;
+    /** Maximum total value (Σ inner_call.value) permitted in wei as a hex string. */
+    value_cap: HexString;
+    /** Block number after which the session key is no longer valid (exclusive). */
+    expiry_block: number;
+    /**
+     * Root account's PQ signature over the session key authorization hash.
+     * `auth_hash = blake3(0x81 || session_pubkey || target || value_cap || expiry_block || chain_id)`.
+     */
+    root_signature: number[];
+    /** Session key's PQ signature over the tx `sender_signing_hash()`. */
+    session_signature: number[];
+}
+/**
+ * Guardian recovery configuration stored on-chain for an account.
+ *
+ * Set via `setGuardians` calldata (use {@link encodeSetGuardiansCalldata}).
+ */
+export interface GuardianConfig {
+    /** Guardian addresses (1..=5). */
+    guardians: AddressLike[];
+    /** Required votes (k-of-n). */
+    threshold: number;
+    /** Minimum blocks between threshold-reach and execution (≥ 100). */
+    timelock: number;
+}
+/**
+ * Active recovery proposal returned by the `shell_getRecoveryProposal` RPC method
+ * (if implemented by the node).
+ */
+export interface RecoveryProposal {
+    /** Proposed new PQ public key as a hex string. */
+    new_pubkey: HexString;
+    /** Algorithm ID of the new public key. */
+    new_algo: number;
+    /** Guardian addresses that have voted for this proposal. */
+    votes: AddressLike[];
+    /** Block after which `executeRecovery` may be called (0 = threshold not yet met). */
+    maturity_block: number;
 }
 /**
  * A fully-signed Shell Chain transaction ready to broadcast via `shell_sendTransaction`.

package/dist/types.js

@@ -11,3 +11,15 @@ export const AA_BUNDLE_TX_TYPE = 0x7e;
  * Maximum number of inner calls per AA bundle.
  */
 export const AA_MAX_INNER_CALLS = 16;
+// ---------------------------------------------------------------------------
+// AA Phase 2 types (v0.19.0-dev)
+// ---------------------------------------------------------------------------
+/**
+ * Maximum length of `paymaster_context` bytes (256 bytes).
+ */
+export const AA_MAX_PAYMASTER_CONTEXT = 256;
+/**
+ * Extra PQ verify gas cost per session key authorization (2 × PQ_VERIFY_GAS = 20 000).
+ * Added to intrinsic gas when a session key is used.
+ */
+export const AA_SESSION_KEY_GAS_SURCHARGE = 20_000;

package/package.json

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