@aastar/sdk 0.20.7 → 0.20.9

package/dist/kms.d.cts

@@ -0,0 +1,3054 @@
+import { y as UserOperation, P as PackedUserOperation, j as BLSSignatureData, w as TierLevel$1, T as TierConfig, p as GuardStatus, v as PreCheckResult } from './tier-router-DeeVg69O.cjs';
+export { A as ALG_BLS, a as ALG_CUMULATIVE_T2, b as ALG_CUMULATIVE_T3, c as ALG_ECDSA, d as ALG_P256, e as AirAccountClient, f as AirAccountConfig, g as AlgId, B as BLSConfig, h as BLSManager, i as BLSNode, k as BeginAuthenticationResponse, l as BeginRegistrationResponse, m as BeginTransactionVerificationResponse, C as CryptoUtil, n as CumulativeT2SignatureData, o as CumulativeT3SignatureData, D as DEFAULT_PASSKEY_ROUTES, E as ERC4337Utils, G as GasEstimate, q as PasskeyAuthenticationParams, r as PasskeyInfo, s as PasskeyManager, t as PasskeyRegistrationParams, u as PasskeyRoutes, x as TransactionVerificationParams, U as UserOpBuilder, Y as YAAAClient, z as YAAAConfig, F as algIdForTier, H as resolveTier } from './tier-router-DeeVg69O.cjs';
+import { AxiosRequestConfig } from 'axios';
+import { PublicClient, Address, Abi, WalletClient, Hex } from 'viem';
+
+/**
+ * Account record stored by the SDK.
+ */
+interface AccountRecord {
+    userId: string;
+    address: string;
+    signerAddress: string;
+    salt: number | bigint;
+    deployed: boolean;
+    deploymentTxHash: string | null;
+    validatorAddress: string;
+    entryPointVersion: string;
+    factoryAddress: string;
+    createdAt: string;
+    /**
+     * Daily transfer limit in wei, stored as a decimal string (bigint serialization).
+     * "0" or undefined means no guard / no limit.
+     * Written into the factory config at account creation time.
+     */
+    dailyLimit?: string;
+    /**
+     * Guardian addresses and their acceptance signatures.
+     * Present only for accounts created via createAccountWithGuardians().
+     * Required by transfer-manager to reconstruct initCode using createAccountWithDefaults.
+     */
+    guardian1?: string;
+    guardian1Sig?: string;
+    guardian2?: string;
+    guardian2Sig?: string;
+}
+/**
+ * Transfer record stored by the SDK.
+ */
+interface TransferRecord {
+    id: string;
+    userId: string;
+    from: string;
+    to: string;
+    amount: string;
+    data?: string;
+    userOpHash: string;
+    bundlerUserOpHash?: string;
+    transactionHash?: string;
+    status: "pending" | "submitted" | "completed" | "failed";
+    error?: string;
+    nodeIndices: number[];
+    tokenAddress?: string;
+    tokenSymbol?: string;
+    createdAt: string;
+    submittedAt?: string;
+    completedAt?: string;
+    failedAt?: string;
+}
+/**
+ * Paymaster configuration record.
+ */
+interface PaymasterRecord {
+    id?: string;
+    name: string;
+    address: string;
+    apiKey?: string;
+    type: "pimlico" | "stackup" | "alchemy" | "custom";
+    endpoint?: string;
+    createdAt?: string;
+}
+/**
+ * BLS configuration record.
+ */
+interface BlsConfigRecord {
+    signerNodes?: {
+        nodes: Array<{
+            nodeId: string;
+            nodeName: string;
+            apiEndpoint: string;
+            status: string;
+            lastSeen?: string;
+        }>;
+    };
+    discovery?: {
+        seedNodes?: Array<{
+            endpoint: string;
+        }>;
+        discoveryTimeout?: number;
+    };
+}
+/**
+ * Pluggable storage adapter — replaces NestJS DatabaseService.
+ * SDK only manages accounts, transfers, paymasters, and BLS config.
+ * User authentication is NOT handled by the SDK.
+ */
+interface IStorageAdapter {
+    getAccounts(): Promise<AccountRecord[]>;
+    saveAccount(account: AccountRecord): Promise<void>;
+    findAccountByUserId(userId: string): Promise<AccountRecord | null>;
+    updateAccount(userId: string, updates: Partial<AccountRecord>): Promise<void>;
+    saveTransfer(transfer: TransferRecord): Promise<void>;
+    findTransfersByUserId(userId: string): Promise<TransferRecord[]>;
+    findTransferById(id: string): Promise<TransferRecord | null>;
+    updateTransfer(id: string, updates: Partial<TransferRecord>): Promise<void>;
+    getPaymasters(userId: string): Promise<PaymasterRecord[]>;
+    savePaymaster(userId: string, paymaster: PaymasterRecord): Promise<void>;
+    removePaymaster(userId: string, name: string): Promise<boolean>;
+    getBlsConfig(): Promise<BlsConfigRecord | null>;
+    updateSignerNodesCache(nodes: unknown[]): Promise<void>;
+}
+
+/**
+ * Optional logger interface for server SDK.
+ * Implement this to integrate with your application's logging framework.
+ */
+interface ILogger {
+    debug(message: string, ...args: unknown[]): void;
+    log(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Default console logger used when no custom logger is provided.
+ */
+declare class ConsoleLogger implements ILogger {
+    private readonly prefix;
+    constructor(prefix?: string);
+    debug(message: string, ...args: unknown[]): void;
+    log(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Silent logger that suppresses all output.
+ */
+declare class SilentLogger implements ILogger {
+    debug(): void;
+    log(): void;
+    warn(): void;
+    error(): void;
+}
+
+/**
+ * Canonical production KMS endpoint (IMX93 TEE behind Cloudflare Tunnel).
+ * v0.20.0 (Beta2) — see AirAccount/kms/CHANGELOG.md.
+ */
+declare const DEFAULT_KMS_ENDPOINT = "https://kms.aastar.io";
+interface KmsHttpClientOptions {
+    kmsEndpoint?: string;
+    kmsEnabled?: boolean;
+    kmsApiKey?: string;
+    logger?: ILogger;
+}
+/**
+ * Shared low-level HTTP transport for all KMS service classes.
+ *
+ * Centralises axios setup (baseURL, x-api-key), the `enabled` gate, and the three
+ * request flavours the KMS uses:
+ *   - plain JSON         → `post` / `get`
+ *   - AWS-KMS framed     → `amzPost` (adds x-amz-target + x-amz-json-1.1 content type)
+ *   - agent/session JWT  → `postWithBearer` (Authorization: Bearer <jwt>)
+ *
+ * KmsManager and the composed services (agent / session / payment / monitor) all share
+ * one instance so they reuse the same connection config and auth headers.
+ */
+declare class KmsHttpClient {
+    readonly endpoint: string;
+    readonly enabled: boolean;
+    readonly logger: ILogger;
+    private readonly apiKey?;
+    private readonly http;
+    constructor(options: KmsHttpClientOptions);
+    /** Throw if KMS is not enabled — every operation must call this first. */
+    ensureEnabled(): void;
+    /**
+     * Plain JSON POST. The axios `config` arg is only forwarded when defined, so a
+     * config-less call results in `http.post(path, body)` (2 args) — preserving the
+     * exact call shape the existing unit tests assert against.
+     */
+    post<T>(path: string, body?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /** Plain JSON GET. */
+    get<T>(path: string, config?: AxiosRequestConfig): Promise<T>;
+    /** POST with AWS-KMS framing (x-amz-target header) — required for wallet/signing ops. */
+    amzPost<T>(path: string, target: string, body: unknown): Promise<T>;
+    /** POST authenticated with a TEE-issued agent/session JWT (Authorization: Bearer). */
+    postWithBearer<T>(path: string, body: unknown, jwt: string): Promise<T>;
+}
+
+/**
+ * RP id the TA verifies against. The TA hardcodes
+ * `EXPECTED_RP_ID_HASH = SHA-256("aastar.io")` (AirAccount PR#44 / Issue #39);
+ * any other rpId makes the TA reject the assertion with "rpId hash mismatch".
+ */
+declare const DEFAULT_RP_ID = "aastar.io";
+/** Origin embedded in clientDataJSON — must be the RP origin the TA expects. */
+declare const DEFAULT_ORIGIN = "https://aastar.io";
+/**
+ * Placeholder credential id (base64url of "test-credential") matching the
+ * reference ceremony fixtures. Production callers SHOULD pass the credential id
+ * returned by CompleteRegistration for the registered passkey.
+ */
+declare const DEFAULT_CREDENTIAL_ID = "dGVzdC1jcmVkZW50aWFs";
+declare function base64UrlEncode(bytes: Uint8Array): string;
+declare function base64UrlDecode(value: string): Uint8Array;
+/**
+ * WebAuthn AuthenticationResponseJSON (the subset the KMS verifies). This is the
+ * value placed in `WebAuthnAssertion.Credential`.
+ */
+interface WebAuthnAuthenticationCredential {
+    id: string;
+    rawId: string;
+    type: "public-key";
+    response: {
+        clientDataJSON: string;
+        authenticatorData: string;
+        signature: string;
+        userHandle?: string;
+    };
+    clientExtensionResults?: Record<string, unknown>;
+}
+/**
+ * Pluggable passkey signer. The ceremony helper builds clientDataJSON +
+ * authenticatorData and computes the WebAuthn message
+ * (authenticatorData || SHA-256(clientDataJSON)); this signer turns that message
+ * into an ES256 (ECDSA P-256 over SHA-256) DER signature.
+ *
+ * Browser callers back this with the platform authenticator; server/test callers
+ * use {@link P256PasskeySigner}.
+ */
+interface PasskeyCeremonySigner {
+    /** base64url credential id registered with the KMS for this passkey. */
+    readonly credentialId: string;
+    /**
+     * Sign the WebAuthn message (authenticatorData || SHA-256(clientDataJSON)).
+     * MUST return a DER-encoded ES256 signature (ECDSA P-256 with SHA-256 applied
+     * to the message), matching the WebAuthn wire format.
+     */
+    sign(message: Uint8Array): Uint8Array | Promise<Uint8Array>;
+}
+/**
+ * Server/test {@link PasskeyCeremonySigner} backed by a raw P-256 private key
+ * (the passkey bound to the KMS key). Mirrors `p256_helper.py`'s
+ * `make_ceremony_assertion`: ES256 DER signature over the WebAuthn message.
+ */
+declare class P256PasskeySigner implements PasskeyCeremonySigner {
+    readonly credentialId: string;
+    private readonly privateKey;
+    /**
+     * @param privateKey raw 32-byte P-256 scalar (Uint8Array or hex, 0x optional).
+     * @param credentialId base64url credential id (defaults to the reference fixture).
+     */
+    constructor(privateKey: Uint8Array | string, credentialId?: string);
+    /**
+     * Uncompressed (0x04…, 65-byte) P-256 public key hex. Register this with the
+     * KMS via CreateKey `PasskeyPublicKey` (or ChangePasskey) so the TA can verify
+     * assertions produced by this signer.
+     */
+    get publicKeyHex(): string;
+    sign(message: Uint8Array): Uint8Array;
+}
+/**
+ * Build the clientDataJSON bytes embedding the TA-issued one-time challenge.
+ *
+ * Compact JSON (no whitespace) with field order `type, challenge, origin`,
+ * mirroring the reference ceremony. The KMS parses this and asserts the
+ * `challenge` field equals the stored nonce before verifying the signature over
+ * (authenticatorData || SHA-256(clientDataJSON)).
+ */
+declare function buildClientDataJSON(challenge: string, origin?: string): Uint8Array;
+/**
+ * Build authenticatorData = rpIdHash(32) || flags(1) || signCount(4, big-endian).
+ * flags = 0x05 (UP | UV). `signCount` must strictly increase across ceremonies
+ * for the same wallet (anti-clone check); callers performing multiple sequential
+ * signs should pass an incrementing value.
+ */
+declare function buildAuthenticatorData(rpId?: string, signCount?: number): Uint8Array;
+interface BuildCredentialOptions {
+    /** The base64url challenge returned by the begin endpoint. */
+    challenge: string;
+    signer: PasskeyCeremonySigner;
+    rpId?: string;
+    origin?: string;
+    signCount?: number;
+}
+/**
+ * Build a complete WebAuthn AuthenticationResponseJSON for a dynamic TA
+ * challenge: construct clientDataJSON (embedding the challenge) + authenticatorData,
+ * then sign (authenticatorData || SHA-256(clientDataJSON)).
+ */
+declare function buildAuthenticationCredential(opts: BuildCredentialOptions): Promise<WebAuthnAuthenticationCredential>;
+/** Minimal shape returned by BeginAuthentication / begin-grant-session-auth. */
+interface BeginCeremonyResponse {
+    ChallengeId: string;
+    Options: {
+        challenge: string;
+    };
+}
+interface RunCeremonyOptions {
+    signer: PasskeyCeremonySigner;
+    rpId?: string;
+    origin?: string;
+    signCount?: number;
+}
+/**
+ * Run a full WebAuthn challenge-binding ceremony (AirAccount #49):
+ *   1. fetch a one-time TA challenge from the `begin` endpoint,
+ *   2. embed it in clientDataJSON,
+ *   3. build + sign the assertion,
+ *   4. return `{ ChallengeId, Credential }` for the KMS `WebAuthn` /
+ *      `webAuthnAssertion` field.
+ *
+ * `begin` is injected so the same helper serves both the generic
+ * (purpose="authentication") and grant-session (purpose="grant-session")
+ * challenge endpoints.
+ */
+declare function runWebAuthnCeremony(begin: () => Promise<BeginCeremonyResponse>, options: RunCeremonyOptions): Promise<WebAuthnAssertion>;
+/** Fetch a generic authentication challenge (purpose="authentication"). */
+declare function beginAuthenticationChallenge(http: KmsHttpClient, keyId: string): Promise<BeginCeremonyResponse>;
+/** Fetch a grant-session challenge (purpose="grant-session"). */
+declare function beginGrantSessionChallenge(http: KmsHttpClient, keyId: string): Promise<BeginCeremonyResponse>;
+/**
+ * Convenience: run a generic authentication ceremony over an {@link KmsHttpClient}.
+ * Covers DeriveAddress / Sign / SignHash / SignTypedData / agent-key /
+ * p256-session signing paths.
+ */
+declare function runAuthenticationCeremony(http: KmsHttpClient, keyId: string, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<WebAuthnAssertion>;
+/**
+ * Convenience: run a grant-session ceremony over an {@link KmsHttpClient}.
+ * Required by sign-grant-session / sign-p256-grant-session, which reject the
+ * generic 'authentication' challenge for cross-op replay safety.
+ */
+declare function runGrantSessionCeremony(http: KmsHttpClient, keyId: string, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<WebAuthnAssertion>;
+
+interface LegacyPasskeyAssertion {
+    AuthenticatorData: string;
+    ClientDataHash: string;
+    Signature: string;
+}
+interface WebAuthnAssertion {
+    ChallengeId: string;
+    Credential: unknown;
+}
+interface KmsCreateKeyRequest {
+    Description: string;
+    KeyUsage?: string;
+    KeySpec?: string;
+    Origin?: string;
+    PasskeyPublicKey: string;
+}
+interface KmsCreateKeyResponse {
+    KeyMetadata: {
+        KeyId: string;
+        Arn: string;
+        CreationDate: string;
+        Enabled: boolean;
+        Description: string;
+        KeyUsage: string;
+        KeySpec: string;
+        Origin: string;
+        Address?: string;
+    };
+    Mnemonic: string;
+    Address?: string;
+    Status?: string;
+}
+interface KmsSignHashResponse {
+    Signature: string;
+}
+interface KmsBeginRegistrationRequest {
+    Description?: string;
+    UserName?: string;
+    UserDisplayName?: string;
+}
+interface KmsBeginRegistrationResponse {
+    ChallengeId: string;
+    Options: PublicKeyCredentialCreationOptions;
+}
+interface KmsCompleteRegistrationRequest {
+    ChallengeId: string;
+    Credential: unknown;
+    Description?: string;
+}
+interface KmsCompleteRegistrationResponse {
+    KeyId: string;
+    CredentialId: string;
+    Status: string;
+}
+interface KmsBeginAuthenticationRequest {
+    Address?: string;
+    KeyId?: string;
+}
+interface KmsBeginAuthenticationResponse {
+    ChallengeId: string;
+    Options: PublicKeyCredentialRequestOptions;
+}
+interface KmsEip712Domain {
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: string;
+}
+/** One entry in a `types` definition: a struct name and its ordered fields. */
+interface KmsEip712TypeDef {
+    name: string;
+    fields: Array<{
+        name: string;
+        type: string;
+    }>;
+}
+/** One field value for the primary type's message. */
+interface KmsEip712FieldValue {
+    name: string;
+    value: unknown;
+}
+interface KmsSignTypedDataRequest {
+    keyId: string;
+    hdPath?: string;
+    domain: KmsEip712Domain;
+    primaryType: string;
+    types: KmsEip712TypeDef[];
+    message: KmsEip712FieldValue[];
+    /** Required unless a Bearer agent JWT is supplied. Legacy passkeyAssertion is rejected. */
+    webAuthnAssertion?: WebAuthnAssertion;
+}
+interface KmsSignTypedDataResponse {
+    keyId: string;
+    signature: string;
+}
+interface KmsBeginGrantSessionAuthRequest {
+    keyId: string;
+}
+interface KmsBeginGrantSessionAuthResponse {
+    ChallengeId: string;
+    Options: PublicKeyCredentialRequestOptions;
+}
+interface KmsSignGrantSessionRequest {
+    keyId: string;
+    hdPath?: string;
+    chainId: number;
+    verifyingContract: string;
+    account: string;
+    sessionKey: string;
+    expiry: number;
+    contractScope: string;
+    selectorScope: string;
+    velocityLimit: number;
+    velocityWindow: number;
+    callTargets: string[];
+    selectorAllowlist: string[];
+    nonce: number;
+    webAuthnAssertion: WebAuthnAssertion;
+}
+interface KmsSignGrantSessionResponse {
+    keyId: string;
+    signature: string;
+}
+interface KmsSignP256GrantSessionRequest {
+    keyId: string;
+    hdPath?: string;
+    chainId: number;
+    verifyingContract: string;
+    account: string;
+    keyX: string;
+    keyY: string;
+    expiry: number;
+    contractScope: string;
+    selectorScope: string;
+    velocityLimit: number;
+    velocityWindow: number;
+    callTargets: string[];
+    selectorAllowlist: string[];
+    nonce: number;
+    webAuthnAssertion: WebAuthnAssertion;
+}
+interface KmsKeyStatusResponse {
+    KeyId: string;
+    Status: "creating" | "deriving" | "ready" | "error";
+    Address?: string;
+    PublicKey?: string;
+    DerivationPath?: string;
+    Error?: string;
+}
+interface KmsDescribeKeyResponse {
+    KeyMetadata: {
+        KeyId: string;
+        Address?: string;
+        PublicKey?: string;
+        DerivationPath?: string;
+        PasskeyPublicKey?: string;
+        Arn?: string;
+        CreationDate?: string;
+        Enabled?: boolean;
+        Description?: string;
+        KeyUsage?: string;
+        KeySpec?: string;
+        Origin?: string;
+    };
+}
+interface KmsEthereumTransaction {
+    chainId: number;
+    nonce: number;
+    to: string;
+    value: string;
+    gasPrice: string;
+    gas: number;
+    data: string;
+}
+interface KmsSignRequest {
+    KeyId?: string;
+    Address?: string;
+    DerivationPath?: string;
+    /** Provide exactly one of Message or Transaction. */
+    Message?: string;
+    Transaction?: KmsEthereumTransaction;
+    SigningAlgorithm?: string;
+    WebAuthn?: WebAuthnAssertion;
+    Passkey?: LegacyPasskeyAssertion;
+}
+interface KmsSignResponse {
+    Signature: string;
+    TransactionHash?: string;
+}
+interface KmsGetPublicKeyResponse {
+    KeyId: string;
+    PublicKey: string;
+    Address?: string;
+    KeyUsage?: string;
+    KeySpec?: string;
+}
+interface KmsDeriveAddressResponse {
+    Address: string;
+    PublicKey?: string;
+}
+interface KmsListKeysResponse {
+    Keys: Array<{
+        KeyId: string;
+        KeyArn?: string;
+    }>;
+    Truncated?: boolean;
+    NextMarker?: string;
+}
+interface KmsDeleteKeyResponse {
+    KeyId: string;
+    DeletionDate?: string;
+}
+interface KmsChangePasskeyResponse {
+    KeyId: string;
+    Changed: boolean;
+}
+interface KmsUnfreezeKeyResponse {
+    KeyId: string;
+    LifecycleStatus: string;
+}
+/**
+ * KMS service for remote key management with WebAuthn/Passkey integration.
+ *
+ * Targets the AAStar TEE KMS (v0.20.0, kms.aastar.io). WebAuthn registration /
+ * authentication ceremonies are handled by the KMS directly; signing operations
+ * require a Passkey assertion (Legacy hex) or a one-time WebAuthn ceremony.
+ *
+ * Wraps a shared {@link KmsHttpClient}; the composed services (agent / session /
+ * payment / monitor) reuse the same client via {@link KmsManager.httpClient}.
+ */
+declare class KmsManager {
+    private readonly client;
+    readonly logger: ILogger;
+    constructor(options: {
+        kmsEndpoint?: string;
+        kmsEnabled?: boolean;
+        kmsApiKey?: string;
+        logger?: ILogger;
+    });
+    isKmsEnabled(): boolean;
+    /** Shared HTTP transport — pass to KmsAgentService / KmsSessionService / etc. */
+    get httpClient(): KmsHttpClient;
+    private ensureEnabled;
+    /** POST with x-amz-target header (required for wallet/signing operations). */
+    private amzPost;
+    createKey(description: string, passkeyPublicKey: string): Promise<KmsCreateKeyResponse>;
+    getKeyStatus(keyId: string): Promise<KmsKeyStatusResponse>;
+    describeKey(keyId: string): Promise<KmsDescribeKeyResponse>;
+    /** Get a key's public key (uncompressed). Not WebAuthn-gated. */
+    getPublicKey(target: {
+        KeyId?: string;
+        Address?: string;
+    }): Promise<KmsGetPublicKeyResponse>;
+    /**
+     * Derive an Ethereum address at a BIP-44 path (WebAuthn-gated).
+     * Provide a WebAuthn ceremony assertion (preferred) or a Legacy passkey assertion.
+     */
+    deriveAddress(params: {
+        KeyId: string;
+        DerivationPath: string;
+        WebAuthn?: WebAuthnAssertion;
+        Passkey?: LegacyPasskeyAssertion;
+    }): Promise<KmsDeriveAddressResponse>;
+    /** List keys (paginated). Not WebAuthn-gated. */
+    listKeys(params?: {
+        Limit?: number;
+        Marker?: string;
+    }): Promise<KmsListKeysResponse>;
+    /**
+     * Schedule key deletion (AWS-KMS action ScheduleKeyDeletion; WebAuthn-gated).
+     * RPMB-bound on the TEE — requires a passkey/WebAuthn assertion on the normal path.
+     */
+    deleteKey(params: {
+        KeyId: string;
+        PendingWindowInDays?: number;
+        WebAuthn?: WebAuthnAssertion;
+        Passkey?: LegacyPasskeyAssertion;
+    }): Promise<KmsDeleteKeyResponse>;
+    /**
+     * Unfreeze a dormant (frozen) key (issue #42; WebAuthn-gated).
+     * A key auto-frozen by the dormant-key sweep rejects signing until unfrozen.
+     * The TEE verifies the owner via the same strict WebAuthn ceremony as
+     * {@link deleteKey}; ownership is checked even when the key is already active,
+     * so this cannot be used as an unauthenticated key-state probe. Unlike DeleteKey
+     * this endpoint takes no `x-amz-target` header — it authenticates via the default
+     * API key plus the WebAuthn assertion in the body.
+     */
+    unfreezeKey(params: {
+        KeyId: string;
+        WebAuthn?: WebAuthnAssertion;
+    }): Promise<KmsUnfreezeKeyResponse>;
+    /**
+     * Rotate the WebAuthn passkey bound to a key (WebAuthn-gated, RPMB-bound).
+     * `PasskeyPublicKey` is the NEW P-256 public key (0x04… 65-byte uncompressed).
+     */
+    changePasskey(params: {
+        KeyId: string;
+        PasskeyPublicKey: string;
+        WebAuthn?: WebAuthnAssertion;
+        Passkey?: LegacyPasskeyAssertion;
+    }): Promise<KmsChangePasskeyResponse>;
+    /**
+     * Sign a message or an EIP-155 transaction (WebAuthn-gated).
+     * Provide exactly one of `Message` (hex) or `Transaction`. For a raw 32-byte
+     * digest use {@link signHash} / {@link signHashWithWebAuthn} instead.
+     */
+    sign(params: KmsSignRequest): Promise<KmsSignResponse>;
+    /**
+     * Poll KeyStatus until the key is ready (address derived) or timeout.
+     * STM32 key derivation takes 60-75 seconds on first creation.
+     */
+    pollUntilReady(keyId: string, timeoutMs?: number, intervalMs?: number): Promise<KmsKeyStatusResponse>;
+    /**
+     * Sign a hash using Legacy Passkey assertion (reusable for BLS dual-signing).
+     */
+    signHash(hash: string, assertion: LegacyPasskeyAssertion, target: {
+        Address?: string;
+        KeyId?: string;
+    }): Promise<KmsSignHashResponse>;
+    /**
+     * Sign a hash using a WebAuthn ceremony assertion (one-time use).
+     */
+    signHashWithWebAuthn(hash: string, challengeId: string, credential: unknown, target: {
+        Address?: string;
+        KeyId?: string;
+    }): Promise<KmsSignHashResponse>;
+    /**
+     * Sign arbitrary EIP-712 typed data via `POST /kms/SignTypedData` (v0.20.0).
+     *
+     * The KMS hashes the typed data host-side, so the FULL EIP-712 structure
+     * (domain / primaryType / types / message) is sent — not a pre-hashed
+     * domainSeparator/structHash. The `webAuthnAssertion` challenge comes from a
+     * generic {@link beginAuthentication} ceremony (purpose="authentication").
+     *
+     * Alternatively, agents authenticate with a Bearer JWT — see KmsAgentService.
+     */
+    signTypedDataWithWebAuthn(params: KmsSignTypedDataRequest): Promise<KmsSignTypedDataResponse>;
+    /**
+     * Begin a grant-session WebAuthn challenge.
+     * The returned challengeId can ONLY be used with sign-grant-session, not sign-typed-data.
+     */
+    beginGrantSessionAuth(params: KmsBeginGrantSessionAuthRequest): Promise<KmsBeginGrantSessionAuthResponse>;
+    /**
+     * Sign a GRANT_SESSION_V2 hash off-chain inside the TEE (secp256k1 session key).
+     * Returns a 65-byte signature (R||S||V, V=27/28) for use in grantSessionWithSig().
+     */
+    signGrantSession(params: KmsSignGrantSessionRequest): Promise<KmsSignGrantSessionResponse>;
+    /**
+     * Sign a GRANT_P256_SESSION_V2 hash off-chain inside the TEE (P256 session key).
+     * Returns a 65-byte signature for use in grantP256SessionWithSig().
+     */
+    signP256GrantSession(params: KmsSignP256GrantSessionRequest): Promise<KmsSignGrantSessionResponse>;
+    /**
+     * Run a generic authentication ceremony (purpose="authentication") bound to a
+     * fresh TA challenge. The returned assertion is valid for DeriveAddress / Sign
+     * / SignHash / SignTypedData / agent-key / p256-session signing.
+     */
+    runAuthenticationCeremony(keyId: string, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<WebAuthnAssertion>;
+    /**
+     * Run a grant-session ceremony (purpose="grant-session") bound to a fresh TA
+     * challenge — required by {@link signGrantSession} / {@link signP256GrantSession}
+     * (the generic 'authentication' challenge is rejected there for replay safety).
+     */
+    runGrantSessionCeremony(keyId: string, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<WebAuthnAssertion>;
+    /** Derive an address, running the challenge-binding ceremony internally. */
+    deriveAddressWithCeremony(params: {
+        KeyId: string;
+        DerivationPath: string;
+    }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsDeriveAddressResponse>;
+    /**
+     * Sign a message or EIP-155 transaction, running the challenge-binding ceremony
+     * internally. `params.KeyId` is required (it identifies the wallet to challenge).
+     */
+    signWithCeremony(params: Omit<KmsSignRequest, "WebAuthn" | "Passkey"> & {
+        KeyId: string;
+    }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignResponse>;
+    /** Sign a 32-byte digest, running the challenge-binding ceremony internally. */
+    signHashWithCeremony(hash: string, target: {
+        KeyId: string;
+    }, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignHashResponse>;
+    /** Sign EIP-712 typed data, running the challenge-binding ceremony internally. */
+    signTypedDataWithCeremony(params: Omit<KmsSignTypedDataRequest, "webAuthnAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignTypedDataResponse>;
+    /**
+     * Sign a GRANT_SESSION_V2 hash, running the grant-session ceremony internally
+     * (uses the purpose-bound `begin-grant-session-auth` challenge).
+     */
+    signGrantSessionWithCeremony(params: Omit<KmsSignGrantSessionRequest, "webAuthnAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignGrantSessionResponse>;
+    /**
+     * Sign a GRANT_P256_SESSION_V2 hash, running the grant-session ceremony
+     * internally (uses the purpose-bound `begin-grant-session-auth` challenge).
+     */
+    signP256GrantSessionWithCeremony(params: Omit<KmsSignP256GrantSessionRequest, "webAuthnAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsSignGrantSessionResponse>;
+    beginRegistration(params: KmsBeginRegistrationRequest): Promise<KmsBeginRegistrationResponse>;
+    completeRegistration(params: KmsCompleteRegistrationRequest): Promise<KmsCompleteRegistrationResponse>;
+    beginAuthentication(params: KmsBeginAuthenticationRequest): Promise<KmsBeginAuthenticationResponse>;
+    /**
+     * Begin a generic WebAuthn authentication ceremony for a key, returning a
+     * challenge usable for SignHash / SignTypedData (purpose="authentication").
+     *
+     * NOTE: there is no dedicated `begin-webauthn-auth` endpoint — this delegates
+     * to `POST /BeginAuthentication`. (Grant-session signing needs a purpose-bound
+     * challenge from {@link beginGrantSessionAuth} instead.)
+     */
+    beginWebAuthnAuth(keyId: string): Promise<KmsBeginAuthenticationResponse>;
+    createKmsSigner(keyId: string, address: string, assertionProvider: () => Promise<LegacyPasskeyAssertion>): KmsSigner;
+}
+/**
+ * KMS-backed signer with Passkey assertion.
+ *
+ * Each signing operation calls the `assertionProvider` to obtain a Legacy
+ * Passkey assertion, which is then passed to KMS SignHash. The Legacy format
+ * is reusable (no challenge consumption), enabling BLS dual-signing.
+ *
+ * Narrowed during the ethers -> viem migration: only the EIP-191 personal-sign
+ * and address-read behaviour is actually consumed by the SDK, so the former
+ * ethers.AbstractSigner surface (signTransaction / signTypedData / connect /
+ * provider) has been dropped.
+ */
+declare class KmsSigner {
+    private readonly keyId;
+    private readonly _address;
+    private readonly kmsManager;
+    private readonly assertionProvider;
+    constructor(keyId: string, _address: string, kmsManager: KmsManager, assertionProvider: () => Promise<LegacyPasskeyAssertion>);
+    getAddress(): Promise<string>;
+    signMessage(message: string | Uint8Array): Promise<string>;
+}
+
+/**
+ * Context for passing Passkey assertion data through the signing chain.
+ * Used by KMS-backed signers to authenticate signing operations.
+ */
+interface PasskeyAssertionContext {
+    assertion: LegacyPasskeyAssertion;
+}
+/**
+ * Pluggable signer adapter — replaces NestJS AuthService wallet management.
+ * Implement this to provide signing capabilities from your key management system.
+ *
+ * Narrow by design: the only operations the SDK performs are EOA address
+ * lookup and EIP-191 personal-sign over a digest. There is no transaction
+ * signing / provider connection — that lives in the bundler/UserOp path.
+ */
+interface ISignerAdapter {
+    /** Get the EOA address for a given user. */
+    getAddress(userId: string): Promise<`0x${string}`>;
+    /**
+     * Sign a message for a given user, applying EIP-191 personal-sign semantics
+     * (equivalent to ethers `signer.signMessage(bytes)` / viem
+     * `account.signMessage({ raw: bytes })`). A `Uint8Array` (or raw `0x` hex) is
+     * signed as raw bytes — callers pass a 32-byte digest, NOT UTF-8 text.
+     *
+     * @param ctx optional Passkey assertion context for KMS-backed signers.
+     */
+    signMessage(userId: string, message: `0x${string}` | Uint8Array, ctx?: PasskeyAssertionContext): Promise<`0x${string}`>;
+    /**
+     * Ensure a signer exists for the user (create on demand if needed).
+     * Returns the signer's address.
+     */
+    ensureSigner(userId: string): Promise<{
+        address: `0x${string}`;
+    }>;
+}
+
+/**
+ * Per-version EntryPoint configuration.
+ */
+interface EntryPointVersionConfig {
+    entryPointAddress: string;
+    factoryAddress: string;
+    validatorAddress: string;
+}
+/**
+ * Server SDK configuration — replaces NestJS ConfigService.
+ */
+interface ServerConfig {
+    /** Main network RPC URL. */
+    rpcUrl: string;
+    /** Bundler RPC URL (e.g. Pimlico, StackUp). */
+    bundlerRpcUrl: string;
+    /** Chain ID of the target network. */
+    chainId: number;
+    /** EntryPoint configurations — at least one version must be provided. */
+    entryPoints: {
+        v06?: EntryPointVersionConfig;
+        v07?: EntryPointVersionConfig;
+        v08?: EntryPointVersionConfig;
+    };
+    /** Default EntryPoint version to use when not specified. */
+    defaultVersion?: "0.6" | "0.7" | "0.8";
+    /** BLS signer seed nodes for gossip discovery. */
+    blsSeedNodes?: string[];
+    /** Timeout for BLS node discovery in ms. */
+    blsDiscoveryTimeout?: number;
+    /** KMS endpoint URL (optional, for KMS-based signing). */
+    kmsEndpoint?: string;
+    /** Whether KMS signing is enabled. */
+    kmsEnabled?: boolean;
+    /** KMS API key for authenticated requests. */
+    kmsApiKey?: string;
+    /** Storage adapter (required). */
+    storage: IStorageAdapter;
+    /** Signer adapter (required). */
+    signer: ISignerAdapter;
+    /** Logger (optional, defaults to ConsoleLogger). */
+    logger?: ILogger;
+}
+/** AirAccount contract version selection.
+ * - "M7"   — r4 audit-final (default). Use for all new account creation.
+ * - "M7r6" — r6 deployment (2026-03-29, superseded). Use ONLY to recover existing r6-deployed accounts.
+ * - "M5"   — legacy 6-field InitConfig deployment.
+ */
+type AirAccountVersion = "M5" | "M7" | "M7r6";
+/**
+ * Build a pre-configured EntryPointVersionConfig for Sepolia using a known AirAccount deployment.
+ * Eliminates the need to look up contract addresses manually.
+ *
+ * @example
+ * // Use M7 r4 audit-final (default)
+ * const config = { entryPoints: { v07: sepoliaV07Config() }, ... };
+ *
+ * // Recover an existing r6-deployed account (do NOT use for new accounts)
+ * const config = { entryPoints: { v07: sepoliaV07Config("M7r6") }, ... };
+ *
+ * // Use M5 legacy
+ * const config = { entryPoints: { v07: sepoliaV07Config("M5") }, ... };
+ */
+declare function sepoliaV07Config(version?: AirAccountVersion): EntryPointVersionConfig;
+/**
+ * Validate a ServerConfig and throw descriptive errors for missing fields.
+ */
+declare function validateConfig(config: ServerConfig): void;
+
+declare enum EntryPointVersion {
+    V0_6 = "0.6",
+    V0_7 = "0.7",
+    V0_8 = "0.8"
+}
+interface EntryPointConfig {
+    version: EntryPointVersion;
+    address: string;
+    factoryAddress: string;
+    validatorAddress: string;
+}
+/** Default EntryPoint addresses (same on Sepolia, Mainnet, and OP Mainnet). */
+declare const ENTRYPOINT_ADDRESSES: {
+    "0.6": {
+        sepolia: string;
+        mainnet: string;
+        optimism: string;
+    };
+    "0.7": {
+        sepolia: string;
+        mainnet: string;
+        optimism: string;
+    };
+    "0.8": {
+        sepolia: string;
+        mainnet: string;
+        optimism: string;
+    };
+};
+declare const ENTRYPOINT_ABI_V6: string[];
+declare const ENTRYPOINT_ABI_V7_V8: string[];
+declare const FACTORY_ABI_V6: string[];
+declare const FACTORY_ABI_V7_V8: string[];
+declare const ACCOUNT_ABI: string[];
+declare const VALIDATOR_ABI: string[];
+declare const AIRACCOUNT_ADDRESSES: {
+    sepolia: {
+        factoryM4: string;
+        factoryM5: string;
+        /** @deprecated defaultCommunityGuardian was address(0); superseded by r6 and r4. Do not use for new accounts. */
+        factoryM7r5Prev: string;
+        /** @deprecated Use {@link factory} (r4 audit-final) for new accounts. */
+        factoryM7r6: string;
+        /** @deprecated Use {@link accountImpl} (r4 audit-final). */
+        accountImplM7r6: string;
+        /** @deprecated Use {@link compositeValidator} (r4 audit-final). */
+        compositeValidatorM7r6: string;
+        /** @deprecated Use {@link tierGuardHook} (r4 audit-final). */
+        tierGuardHookM7r6: string;
+        /** @deprecated Use {@link agentSessionKeyValidator} (r4 audit-final). */
+        agentSessionKeyValidatorM7r6: string;
+        /** @deprecated Use factory (beta.4) for new accounts. */
+        factoryM7r4: string;
+        /** @deprecated */
+        accountImplM7r4: string;
+        /** @deprecated Use validatorRouter. */
+        validatorRouterM7r4: string;
+        /** @deprecated */
+        compositeValidatorM7r4: string;
+        /** @deprecated */
+        tierGuardHookM7r4: string;
+        /** @deprecated */
+        agentSessionKeyValidatorM7r4: string;
+        factory: "0x52c5190E7308Ea9B149157FF016cC99B6C6bf984";
+        factoryM7: "0x52c5190E7308Ea9B149157FF016cC99B6C6bf984";
+        accountImpl: "0x7fe62d512f0b8238DE6Ff17175DcE40eA312bBF2";
+        validatorRouter: "0xC20A986Bcd5bF5Cc2fE5fFde6b155B8419E0389e";
+        blsAlgorithm: "0x68c381Ad3A2e3380F22840008027E9Ec2783F43A";
+        blsAggregator: "0x77f7bf95B8602b7851f392F412257539242947e0";
+        superPaymaster: "0x030025f40d509b1a99547bAEb3795bD27F7182b7";
+        sessionKeyValidator: "0x70de2e36004d6Ddc24DEB80e1Ef76c03EdC0c2AE";
+        forceExitModule: "0xd882a16Ea37Be463D1885EF4a397Dbbf157dC211";
+        airAccountDelegate: "0xA8D7f70c9D36bC4a4eb14F0dCEE19053FCB3309f";
+        airAccountExtension: "0xD61C0F3DE6D98070E9986743d35A56d56855A249";
+        agentRegistry: "0x3895b3E6fEf4e121E6289dC7881A0eEd5283C652";
+        calldataParserRegistry: "0xb8Af1C039dF88F6bD9fE36Ca683492a3c09e7D17";
+        uniswapV3Parser: string;
+    };
+};
+declare const AIRACCOUNT_ABI: string[];
+declare const AIRACCOUNT_FACTORY_ABI: string[];
+declare const GLOBAL_GUARD_ABI: string[];
+declare const ERC20_ABI: string[];
+declare const AGENT_SESSION_KEY_VALIDATOR_ABI: string[];
+declare const TIER_GUARD_HOOK_ABI: string[];
+declare const AIR_ACCOUNT_COMPOSITE_VALIDATOR_ABI: string[];
+declare const FORCE_EXIT_MODULE_ABI: string[];
+declare const MODULE_TYPE: {
+    readonly VALIDATOR: 1;
+    readonly EXECUTOR: 2;
+    readonly FALLBACK: 3;
+    readonly HOOK: 4;
+};
+declare const ALG_ID: {
+    readonly BLS: 1;
+    readonly ECDSA: 2;
+    readonly P256: 3;
+    readonly CUMULATIVE_T2: 4;
+    readonly CUMULATIVE_T3: 5;
+    readonly COMBINED_T1: 6;
+    readonly WEIGHTED: 7;
+    readonly SESSION_KEY: 8;
+    readonly AGENT_SESSION_KEY: 9;
+};
+declare const SESSION_KEY_VALIDATOR_ABI: string[];
+declare const CALLDATA_PARSER_REGISTRY_ABI: string[];
+declare const AIR_ACCOUNT_DELEGATE_ABI: string[];
+
+/**
+ * A viem contract instance bound to a read-only PublicClient.
+ *
+ * The EntryPoint/AirAccount ABIs are loaded from human-readable signatures via
+ * `parseAbi`, which yields the loosely-typed `Abi` shape. As a result `read`/`write`
+ * method access is not statically typed per-function; callers index by name and the
+ * returned value is `unknown` (cast at the call site). This mirrors the dynamic
+ * surface that `ethers.Contract` previously exposed.
+ */
+type ViemContractMethods = Record<string, (...args: unknown[]) => Promise<unknown>>;
+interface ViemContract {
+    address: Address;
+    abi: Abi;
+    /** Read (view/pure) calls: `contract.read.fnName([...args])`. */
+    read: ViemContractMethods;
+    /** State-changing calls (requires a wallet client — not provided by this read-only hub). */
+    write: ViemContractMethods;
+    estimateGas: ViemContractMethods;
+    simulate: ViemContractMethods;
+    getEvents: ViemContractMethods;
+}
+/**
+ * Unified Ethereum provider — replaces NestJS EthereumService.
+ * Manages RPC + Bundler clients (viem) and contract interactions.
+ */
+declare class EthereumProvider {
+    /** Main-network read client. Pass to viem getContract / readContract calls. */
+    private readonly provider;
+    /** Bundler client — used only for raw eth_ / pimlico_ userOp JSON-RPC. */
+    private readonly bundlerProvider;
+    private readonly config;
+    private readonly logger;
+    constructor(config: ServerConfig);
+    /** Returns the viem PublicClient for the main network RPC. */
+    getProvider(): PublicClient;
+    /** Returns the viem PublicClient bound to the bundler RPC (raw .request only). */
+    getBundlerProvider(): PublicClient;
+    /**
+     * Raw bundler JSON-RPC call. The bundler exposes non-standard methods
+     * (eth_sendUserOperation, pimlico_getUserOperationGasPrice, ...) that are not in
+     * viem's typed RPC schema, so we go through the transport's request fn untyped.
+     */
+    private bundlerRequest;
+    private getVersionConfig;
+    getEntryPointAddress(version: EntryPointVersion): string;
+    getFactoryAddress(version: EntryPointVersion): string;
+    getValidatorAddress(version: EntryPointVersion): string;
+    getDefaultVersion(): EntryPointVersion;
+    /** Build a read-only viem contract bound to the main-network PublicClient. */
+    private contractAt;
+    getFactoryContract(version?: EntryPointVersion): ViemContract;
+    getEntryPointContract(version?: EntryPointVersion): ViemContract;
+    getValidatorContract(version?: EntryPointVersion): ViemContract;
+    getAccountContract(address: string): ViemContract;
+    getAgentSessionKeyValidatorContract(address?: string): ViemContract;
+    getTierGuardHookContract(address?: string): ViemContract;
+    getCompositeValidatorContract(address?: string): ViemContract;
+    getForceExitModuleContract(address: string): ViemContract;
+    getBalance(address: string): Promise<string>;
+    getNonce(accountAddress: string, key?: number, version?: EntryPointVersion): Promise<bigint>;
+    getUserOpHash(userOp: UserOperation | PackedUserOperation, version?: EntryPointVersion): Promise<string>;
+    estimateUserOperationGas(userOp: unknown, version?: EntryPointVersion): Promise<{
+        callGasLimit: string;
+        verificationGasLimit: string;
+        preVerificationGas: string;
+    }>;
+    sendUserOperation(userOp: unknown, version?: EntryPointVersion): Promise<string>;
+    getUserOperationReceipt(userOpHash: string): Promise<unknown>;
+    waitForUserOp(userOpHash: string, maxAttempts?: number): Promise<string>;
+    getUserOperationGasPrice(): Promise<{
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+    }>;
+}
+
+/**
+ * Account manager — extracted from NestJS AccountService.
+ * Creates and retrieves smart accounts without framework dependencies.
+ */
+declare class AccountManager {
+    private readonly ethereum;
+    private readonly storage;
+    private readonly signer;
+    private readonly logger;
+    constructor(ethereum: EthereumProvider, storage: IStorageAdapter, signer: ISignerAdapter, logger?: ILogger);
+    createAccount(userId: string, options?: {
+        entryPointVersion?: EntryPointVersion;
+        salt?: number | bigint;
+        /** Daily transfer limit in wei. When > 0 the account is created with on-chain guard enforcement. */
+        dailyLimit?: bigint;
+    }): Promise<AccountRecord>;
+    getAccount(userId: string): Promise<(AccountRecord & {
+        balance: string;
+        nonce: string;
+    }) | null>;
+    getAccountAddress(userId: string): Promise<string>;
+    getAccountBalance(userId: string): Promise<{
+        address: string;
+        balance: string;
+        balanceInWei: string;
+    }>;
+    getAccountNonce(userId: string): Promise<{
+        address: string;
+        nonce: string;
+    }>;
+    getAccountByUserId(userId: string): Promise<AccountRecord | null>;
+    /**
+     * Build the acceptance hash that guardian devices must sign before account creation.
+     *
+     * Encoding: keccak256(solidityPacked(
+     *   ["string","uint256","address","address","uint256","uint256"],
+     *   ["ACCEPT_GUARDIAN", chainId, factoryAddress, owner, salt, dailyLimit]
+     * ))
+     *
+     * dailyLimit is bound in the hash (PR #47 / C-3) to prevent a front-runner from
+     * replaying guardian sigs with a weaker limit on the same counterfactual address.
+     *
+     * Returns the RAW keccak256 hash (no EIP-191 prefix).
+     * Guardians MUST sign via personal_sign / ethers.signMessage(ethers.getBytes(hash)).
+     * Do NOT use eth_sign — the EIP-191 "\x19Ethereum Signed Message:\n32" prefix
+     * is applied inside the contract (toEthSignedMessageHash) before ecrecover, not here.
+     *
+     * @returns raw hex keccak256 hash — encode this into the QR code shown to guardian devices
+     */
+    buildGuardianAcceptanceHash(owner: string, salt: number | bigint, factoryAddress: string, chainId: number, dailyLimit: bigint): string;
+    /**
+     * Encode calldata for modifyTierLimitsWithGuardians() — guardian-gated tier-limit change (PR #43).
+     *
+     * Both tier1 and tier2 can be raised or lowered, subject to guardian approval.
+     * Caller is responsible for building and submitting the resulting UserOp.
+     *
+     * @param tier1        New Tier-1 ceiling in wei (ECDSA-only spending; 0 = no limit)
+     * @param tier2        New Tier-2 ceiling in wei (dual-factor; 0 = no limit)
+     * @param deadline     Unix timestamp — guardian sigs rejected after this
+     * @param guardianSigs 65-byte EIP-191 hex signatures from required guardians
+     */
+    encodeModifyTierLimits(tier1: bigint, tier2: bigint, deadline: bigint, guardianSigs: string[]): string;
+    /**
+     * Create an AirAccount with 3 on-chain guardians:
+     *   - guardian1 and guardian2: user's own devices (passkeys on phone 1 and phone 2)
+     *   - guardian3: team Safe multisig (defaultCommunityGuardian, set in factory at deploy time)
+     *
+     * Both guardian1 and guardian2 must sign the acceptance hash produced by
+     * buildGuardianAcceptanceHash() before this method is called.
+     *
+     * Recovery: any 2-of-3 guardians can initiate social recovery after a 48h timelock.
+     */
+    createAccountWithGuardians(userId: string, params: {
+        guardian1: string;
+        guardian1Sig: string;
+        guardian2: string;
+        guardian2Sig: string;
+        dailyLimit: bigint;
+        salt?: number | bigint;
+        entryPointVersion?: EntryPointVersion;
+    }): Promise<AccountRecord>;
+}
+
+/**
+ * Minimal guardian signer surface (was `ethers.Signer`): an external signer that
+ * performs an EIP-191 personal-sign over raw bytes and returns a 0x-prefixed
+ * 65-byte hex signature. Structural — any ethers/viem signer with this method fits.
+ */
+interface GuardianSigner {
+    signMessage(message: Uint8Array): Promise<string>;
+}
+
+/**
+ * Raised when a DVT node (aNode YetAnotherAA-Validator ≥ v1.3.0, running with
+ * `CONFIRM_ENABLED=true`) withholds its co-signature on a high-value op pending
+ * out-of-band approval. The node returns `{ status: "pending_confirmation",
+ * userOpHash }` instead of a signature; the withheld co-sign is released by
+ * `POST /signature/confirm { userOpHash, token }` once the user approves over an
+ * independent channel (single-use token, TTL, fail-closed). The SDK surfaces this
+ * as a typed error rather than silently dropping the node so callers can drive the
+ * confirm flow. Default-off nodes never emit this (behaviour == v1.2.0).
+ */
+declare class DvtPendingConfirmationError extends Error {
+    readonly userOpHash: string;
+    readonly nodeEndpoint: string;
+    constructor(userOpHash: string, nodeEndpoint: string);
+}
+/**
+ * Type guard for a DVT v1.3.0 `/signature/sign` response that withheld its
+ * co-signature pending out-of-band confirmation (`{ status: "pending_confirmation",
+ * userOpHash }`). Used at every sign call site so a high-value-op withhold is
+ * surfaced, not mistaken for a signature-less failure. Default-off nodes never
+ * return this shape.
+ */
+declare function isPendingConfirmation(data: unknown): data is {
+    status: "pending_confirmation";
+    userOpHash?: string;
+};
+/**
+ * BLS signature service — extracted from NestJS BlsService.
+ * Uses lazy initialization instead of onModuleInit.
+ */
+declare class BLSSignatureService {
+    private readonly config;
+    private readonly ethereum;
+    private readonly storage;
+    private readonly signer;
+    private blsManager;
+    private readonly logger;
+    constructor(config: ServerConfig, ethereum: EthereumProvider, storage: IStorageAdapter, signer: ISignerAdapter, logger?: ILogger);
+    /** Lazy-initialize BLSManager on first use. */
+    private ensureInitialized;
+    getActiveSignerNodes(): Promise<unknown[]>;
+    generateBLSSignature(userId: string, userOpHash: string, ctx?: PasskeyAssertionContext): Promise<BLSSignatureData>;
+    packSignature(blsData: BLSSignatureData): Promise<string>;
+    /**
+     * Generate a tiered signature based on the required tier level.
+     *
+     * - Tier 1: raw 65-byte ECDSA (no algId prefix, backwards-compat)
+     * - Tier 2: algId 0x04 — P256 + BLS aggregate + messagePoint ECDSA
+     * - Tier 3: algId 0x05 — P256 + BLS + messagePoint ECDSA + Guardian ECDSA
+     *
+     * @param tier - Required tier level (1, 2, or 3)
+     * @param userId - User ID for account lookup
+     * @param userOpHash - The UserOp hash to sign
+     * @param p256Signature - P256 passkey signature (64 bytes, required for tier 2/3)
+     * @param guardianSigner - Guardian signer (required for tier 3)
+     * @param ctx - Optional passkey assertion context for KMS signing
+     */
+    generateTieredSignature(params: {
+        tier: TierLevel$1;
+        userId: string;
+        userOpHash: string;
+        p256Signature?: string;
+        guardianSigner?: GuardianSigner;
+        ctx?: PasskeyAssertionContext;
+    }): Promise<string>;
+}
+
+/**
+ * Pre-checks transactions against GlobalGuard before submitting on-chain.
+ * Avoids wasted gas from predictable reverts.
+ */
+declare class GuardChecker {
+    private readonly ethereum;
+    private readonly logger;
+    constructor(ethereum: EthereumProvider, logger?: ILogger);
+    /**
+     * Fetch tier limits from an AirAccount contract.
+     */
+    fetchTierConfig(accountAddress: string): Promise<TierConfig>;
+    /**
+     * Fetch guard status from the account's GlobalGuard.
+     */
+    fetchGuardStatus(accountAddress: string): Promise<GuardStatus>;
+    /**
+     * Pre-check a transaction: determine tier, check guard limits and algorithm approval.
+     * Returns errors array (empty = OK to proceed).
+     */
+    preCheck(accountAddress: string, value: bigint): Promise<PreCheckResult>;
+}
+
+/**
+ * Thrown when a paymaster's on-chain price cache is stale.
+ * Caller should invoke `paymasterManager.updatePrice(paymasterAddress)` before retrying.
+ */
+declare class PaymasterPriceStalenessError extends Error {
+    readonly paymasterAddress: string;
+    readonly ageSeconds: number;
+    readonly thresholdSeconds: number;
+    constructor(paymasterAddress: string, ageSeconds: number, thresholdSeconds: number);
+}
+/**
+ * Paymaster manager — extracted from NestJS PaymasterService.
+ * Storage via IStorageAdapter instead of filesystem JSON files.
+ */
+declare class PaymasterManager {
+    private readonly ethereum;
+    private readonly storage;
+    private readonly logger;
+    constructor(ethereum: EthereumProvider, storage: IStorageAdapter, logger?: ILogger);
+    getAvailablePaymasters(userId: string): Promise<{
+        name: string;
+        address: string;
+        configured: boolean;
+    }[]>;
+    addCustomPaymaster(userId: string, name: string, address: string, type?: "pimlico" | "stackup" | "alchemy" | "custom", apiKey?: string, endpoint?: string): Promise<void>;
+    removeCustomPaymaster(userId: string, name: string): Promise<boolean>;
+    /**
+     * Check whether a paymaster's on-chain price cache is still fresh.
+     * Returns `{ fresh, ageSeconds, thresholdSeconds }`.
+     * Throws if the contract does not implement `cachedPriceTimestamp()` / `priceStalenessThreshold()`.
+     */
+    checkPriceFreshness(paymasterAddress: string): Promise<{
+        fresh: boolean;
+        ageSeconds: number;
+        thresholdSeconds: number;
+    }>;
+    /**
+     * Call `updatePrice()` on a paymaster contract (permissionless).
+     * Useful when `checkPriceFreshness()` reports stale price.
+     *
+     * @param walletClient - A viem WalletClient (with an account) that will send
+     *   the transaction (must have gas). Replaces the former ethers Signer param.
+     */
+    updatePrice(paymasterAddress: string, walletClient: WalletClient): Promise<string>;
+    getPaymasterData(userId: string, paymasterName: string, userOp: unknown, entryPoint: string, customAddress?: string, options?: {
+        tokenAddress?: string;
+    }): Promise<string>;
+    private getPimlicoPaymasterData;
+    private getStackUpPaymasterData;
+    private getAlchemyPaymasterData;
+}
+
+interface TokenInfo {
+    address: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+}
+interface TokenBalance {
+    token: TokenInfo;
+    balance: string;
+    formattedBalance: string;
+}
+/**
+ * Token service — extracted from NestJS TokenService.
+ * Only on-chain queries and calldata generation (no preset token list).
+ */
+declare class TokenService {
+    private readonly ethereum;
+    constructor(ethereum: EthereumProvider);
+    getTokenInfo(tokenAddress: string): Promise<TokenInfo>;
+    getTokenBalance(tokenAddress: string, walletAddress: string): Promise<string>;
+    getFormattedTokenBalance(tokenAddress: string, walletAddress: string): Promise<TokenBalance>;
+    generateTransferCalldata(to: string, amount: string, decimals: number): string;
+    validateToken(tokenAddress: string): Promise<{
+        isValid: boolean;
+        token?: TokenInfo;
+        error?: string;
+    }>;
+}
+
+interface ExecuteTransferParams {
+    to: string;
+    amount: string;
+    data?: string;
+    tokenAddress?: string;
+    usePaymaster?: boolean;
+    paymasterAddress?: string;
+    paymasterData?: string;
+    /** ERC-20 token address for deposit-pull paymasters (e.g. PMv4) that require
+     *  the gas token address appended to paymasterData. Used when the paymaster
+     *  contract does not expose a public token() getter for auto-detection. */
+    paymasterTokenAddress?: string;
+    passkeyAssertion?: LegacyPasskeyAssertion;
+    /** P256 passkey signature (64 bytes hex). Required for AirAccount Tier 2/3. */
+    p256Signature?: string;
+    /** Guardian signer instance. Required for AirAccount Tier 3. */
+    guardianSigner?: GuardianSigner;
+    /** Enable AirAccount tiered signature routing. Default: false (legacy BLS-only). */
+    useAirAccountTiering?: boolean;
+    /**
+     * Wrap the execute()/executeBatch() callData with the `executeUserOp` selector
+     * (v0.17.2-beta.4 bundler-compat). REQUIRED for guard-enabled accounts submitted
+     * through a standard ERC-4337 bundler; the account re-derives the signature algId
+     * in-frame. Default: false. No-guard accounts and owner-direct calls leave it off.
+     */
+    wrapExecuteUserOp?: boolean;
+}
+interface EstimateGasParams {
+    to: string;
+    amount: string;
+    data?: string;
+    tokenAddress?: string;
+    /** Match the executeUserOp wrapping used at submission so gas estimation is accurate (v0.17.2-beta.4). */
+    wrapExecuteUserOp?: boolean;
+}
+interface TransferResult {
+    success: boolean;
+    transferId: string;
+    userOpHash: string;
+    status: string;
+    message: string;
+    from: string;
+    to: string;
+    amount: string;
+}
+/**
+ * Transfer manager — extracted from NestJS TransferService.
+ * No passkey verification: callers are responsible for their own auth.
+ */
+declare class TransferManager {
+    private readonly ethereum;
+    private readonly accountManager;
+    private readonly blsService;
+    private readonly paymasterManager;
+    private readonly tokenService;
+    private readonly storage;
+    private readonly signer;
+    private readonly logger;
+    private readonly guardChecker;
+    constructor(ethereum: EthereumProvider, accountManager: AccountManager, blsService: BLSSignatureService, paymasterManager: PaymasterManager, tokenService: TokenService, storage: IStorageAdapter, signer: ISignerAdapter, logger?: ILogger, guardChecker?: GuardChecker);
+    executeTransfer(userId: string, params: ExecuteTransferParams): Promise<TransferResult>;
+    private processTransferAsync;
+    estimateGas(userId: string, params: EstimateGasParams): Promise<{
+        callGasLimit: string;
+        verificationGasLimit: string;
+        preVerificationGas: string;
+        validatorGasEstimate: string;
+        totalGasEstimate: string;
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+    }>;
+    getTransferStatus(userId: string, transferId: string): Promise<Record<string, unknown>>;
+    getTransferHistory(userId: string, page?: number, limit?: number): Promise<{
+        transfers: TransferRecord[];
+        total: number;
+        page: number;
+        limit: number;
+        totalPages: number;
+    }>;
+    private buildUserOperation;
+    private formatUserOpForBundler;
+}
+
+/**
+ * Thin wrapper around ISignerAdapter for consistent wallet access.
+ */
+declare class WalletManager {
+    private readonly signer;
+    constructor(signer: ISignerAdapter);
+    getAddress(userId: string): Promise<`0x${string}`>;
+    signMessage(userId: string, message: `0x${string}` | Uint8Array, ctx?: PasskeyAssertionContext): Promise<`0x${string}`>;
+    ensureSigner(userId: string): Promise<{
+        address: `0x${string}`;
+    }>;
+}
+
+/**
+ * Main facade for the YAAA Server SDK.
+ * Wires all services together from a single config object.
+ *
+ * @example
+ * ```ts
+ * import { AirAccountServerClient, MemoryStorage, LocalWalletSigner } from '@aastar/airaccount/server';
+ *
+ * const client = new AirAccountServerClient({
+ *   rpcUrl: 'https://sepolia.infura.io/v3/...',
+ *   bundlerRpcUrl: 'https://api.pimlico.io/v2/11155111/rpc?apikey=...',
+ *   chainId: 11155111,
+ *   entryPoints: {
+ *     v06: {
+ *       entryPointAddress: '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
+ *       factoryAddress: '0x...',
+ *       validatorAddress: '0x...',
+ *     },
+ *   },
+ *   storage: new MemoryStorage(),
+ *   signer: new LocalWalletSigner('0xPRIVATE_KEY'),
+ * });
+ *
+ * const account = await client.accounts.createAccount('user-123');
+ * ```
+ */
+declare class AirAccountServerClient {
+    readonly ethereum: EthereumProvider;
+    readonly accounts: AccountManager;
+    readonly transfers: TransferManager;
+    readonly bls: BLSSignatureService;
+    readonly paymaster: PaymasterManager;
+    readonly tokens: TokenService;
+    readonly wallets: WalletManager;
+    constructor(config: ServerConfig);
+}
+/**
+ * @deprecated Renamed to {@link AirAccountServerClient}. This alias is kept for
+ * backward compatibility and will be removed in a future major version.
+ */
+declare const YAAAServerClient: typeof AirAccountServerClient;
+
+type ModuleTypeId = 1 | 2 | 3 | 4;
+interface InstallModuleParams {
+    /** The deployed AirAccount address */
+    account: string;
+    /** ERC-7579 module type: 1=Validator, 2=Executor, 3=Fallback, 4=Hook */
+    moduleTypeId: ModuleTypeId;
+    /** Module contract address to install */
+    module: string;
+    /**
+     * Guardian signatures + module init data, packed as:
+     *   bytes[0..65*sigsRequired] = guardian ECDSA sigs
+     *   bytes[65*sigsRequired..]  = module onInstall() init data
+     *
+     * Sig hash (per guardian, r5 format):
+     *   keccak256("INSTALL_MODULE" ‖ chainId ‖ account ‖ moduleTypeId ‖ module ‖ keccak256(moduleInitData)).toEthSignedMessageHash()
+     *
+     * sigsRequired: 0 if threshold<=40, 1 if <=70, 2 if =100
+     */
+    guardianSigs?: string[];
+    /** Raw bytes passed to module.onInstall() after guardian sigs */
+    moduleInitData?: string;
+}
+interface UninstallModuleParams {
+    account: string;
+    moduleTypeId: ModuleTypeId;
+    module: string;
+    /** Always requires 2 guardian sigs for uninstall */
+    guardianSig1: string;
+    guardianSig2: string;
+    /** Passed to module.onUninstall() */
+    moduleDeInitData?: string;
+}
+/**
+ * Build the EIP-191 install hash that guardians must sign.
+ *
+ * r5 format: includes keccak256(moduleInitData) to prevent config-swap attacks.
+ *
+ * @example
+ * const hash = buildInstallModuleHash(chainId, account, 1, moduleAddress, moduleInitData);
+ * const sig = await guardian.signMessage(hexToBytes(hash));
+ */
+declare function buildInstallModuleHash(chainId: number, account: string, moduleTypeId: ModuleTypeId, module: string, moduleInitData?: string): string;
+/**
+ * Build the EIP-191 uninstall hash that guardians must sign.
+ */
+declare function buildUninstallModuleHash(chainId: number, account: string, moduleTypeId: ModuleTypeId, module: string): string;
+/**
+ * ModuleManager — ERC-7579 module install/uninstall helpers.
+ *
+ * Handles the guardian-sig packing required by AAStarAirAccountV7:
+ *   installModule(moduleTypeId, module, guardianSigs ‖ moduleInitData)
+ *   uninstallModule(moduleTypeId, module, guardianSig1 ‖ guardianSig2 ‖ deInitData)
+ */
+declare class ModuleManager {
+    private readonly provider;
+    private readonly chainId;
+    constructor(provider: PublicClient, chainId: number);
+    /**
+     * Encode calldata for installModule().
+     * Caller is responsible for submitting via UserOp (EntryPoint) or direct tx.
+     */
+    encodeInstall(params: InstallModuleParams): string;
+    /**
+     * Encode calldata for uninstallModule().
+     * Always requires 2 guardian signatures.
+     */
+    encodeUninstall(params: UninstallModuleParams): string;
+    /** Check if a module is currently installed on the account. */
+    isInstalled(account: string, moduleTypeId: ModuleTypeId, module: string): Promise<boolean>;
+    /** Return the install hash for a guardian to sign (r5 format, includes moduleInitData hash). */
+    installHash(account: string, moduleTypeId: ModuleTypeId, module: string, moduleInitData?: string): string;
+    /** Return the uninstall hash for guardians to sign. */
+    uninstallHash(account: string, moduleTypeId: ModuleTypeId, module: string): string;
+    /**
+     * Convenience: build install calldata for the standard M7 module set.
+     * Uses pre-deployed Sepolia addresses (r4 audit-final). No guardian sigs required when
+     * account threshold <= 40 (default for newly created accounts).
+     *
+     * Note: beta.3 unifies these into SessionKeyValidator. This helper retains the r4
+     * addresses for accounts already deployed on r4; new accounts use SessionKeyValidator.
+     */
+    encodeInstallDefaultModules(account: string): {
+        compositeValidator: string;
+        tierGuardHook: string;
+    };
+}
+
+interface GrantSessionParams {
+    /** Account that owns the session */
+    account: string;
+    /** The session key address (ephemeral EOA) */
+    sessionKey: string;
+    /** Expiry unix timestamp (max 7 days from now) */
+    expiry: number;
+    /** address(0) = any destination allowed */
+    contractScope?: string;
+    /** bytes4(0) = any selector allowed */
+    selectorScope?: string;
+    /** Max calls per velocityWindow (0 = unlimited). Session struct field. */
+    velocityLimit?: number;
+    /** Velocity window in seconds (0 = no window). Session struct field. */
+    velocityWindow?: number;
+    /** Allowed destination addresses ([] = any). Session struct field. */
+    callTargets?: string[];
+    /** Allowed selectors ([] = any). Session struct field. */
+    selectorAllowlist?: string[];
+    /** Owner signature over buildGrantHash() — omit if calling directly from account */
+    ownerSig?: string;
+}
+interface SessionInfo {
+    expiry: number;
+    contractScope: string;
+    selectorScope: string;
+    revoked: boolean;
+    velocityLimit: number;
+    velocityWindow: number;
+    callTargets: string[];
+    selectorAllowlist: string[];
+    active: boolean;
+}
+interface GrantP256SessionParams {
+    /** Account that owns the session */
+    account: string;
+    /** P256 public key X coordinate (0x-prefixed 32-byte hex) */
+    keyX: string;
+    /** P256 public key Y coordinate (0x-prefixed 32-byte hex) */
+    keyY: string;
+    /** Expiry unix timestamp (max 7 days from now) */
+    expiry: number;
+    /** address(0) = any destination allowed */
+    contractScope?: string;
+    /** bytes4(0) = any selector allowed */
+    selectorScope?: string;
+    /** Max calls per velocityWindow (0 = unlimited). Session struct field. */
+    velocityLimit?: number;
+    /** Velocity window in seconds (0 = no window). Session struct field. */
+    velocityWindow?: number;
+    /** Allowed destination addresses ([] = any). Session struct field. */
+    callTargets?: string[];
+    /** Allowed selectors ([] = any). Session struct field. */
+    selectorAllowlist?: string[];
+    /** Owner signature over buildP256GrantHash() — omit if calling directly from the owner EOA */
+    ownerSig?: string;
+}
+interface AgentSessionConfig {
+    expiry: number;
+    velocityLimit: number;
+    velocityWindow: number;
+    callTargets: string[];
+    selectorAllowlist: string[];
+}
+interface AgentSessionInfo extends AgentSessionConfig {
+    revoked: boolean;
+    callCount: bigint;
+    windowStart: bigint;
+}
+/**
+ * SessionKeyService — manage M6 (basic) and M7 (agent) session keys.
+ *
+ * M6 SessionKeyValidator (algId=0x08):
+ *   Simple time-limited ECDSA/P256 key with optional contract+selector scope.
+ *   Used for standard delegated actions (hot wallet, automated tasks).
+ *
+ * M7 AgentSessionKeyValidator (algId=0x09):
+ *   Rich session key for AI agents: velocity limits, spend caps, call allowlists,
+ *   hierarchical delegation (parent → sub-agent with scope narrowing).
+ */
+declare class SessionKeyService {
+    private readonly skValidator;
+    private readonly askValidator;
+    constructor(provider: PublicClient, sessionKeyValidatorAddress: string, agentSessionKeyValidatorAddress: string);
+    /**
+     * Build the hash that the account owner must sign to grant a session key.
+     * Use grantSession() with this sig, or grantSessionDirect() from the account itself.
+     */
+    buildGrantHash(params: Omit<GrantSessionParams, "ownerSig">): Promise<string>;
+    /** Query an ECDSA session key state (decodes the 8-field Session tuple). */
+    getSession(account: string, sessionKey: string): Promise<SessionInfo>;
+    /** Check if an ECDSA session is currently active. */
+    isSessionActive(account: string, sessionKey: string): Promise<boolean>;
+    /**
+     * Encode calldata for session grant.
+     *
+     * - **With ownerSig** → `grantSession()` — for gasless/UserOp flows.
+     *   Owner signs the GRANT_SESSION_V2 typed hash via KMS `sign-grant-session`,
+     *   then the relayer calls `grantSession(account, key, cfg, ownerSig)` on-chain.
+     *   This is the ONLY path for ERC-4337 sponsored / gasless grant flows.
+     *
+     * - **Without ownerSig** → `grantSessionDirect()` — **owner EOA direct-send only**.
+     *   Since v0.17.2 round 3, `grantSessionDirect` requires `msg.sender == ownerOf(account)`.
+     *   It does NOT accept `msg.sender == account` (removed in round 3 — confused-deputy fix).
+     *   Do NOT encode this for a UserOp callData; the EntryPoint is not the owner EOA.
+     */
+    encodeGrantSession(params: GrantSessionParams): string;
+    /** Encode calldata for revokeSession(). */
+    encodeRevokeSession(account: string, sessionKey: string): string;
+    /**
+     * Build the hash that the account owner must sign to grant a P256/passkey session key.
+     * Use grantP256Session() with this sig, or grantP256SessionDirect() from the owner EOA itself.
+     * The owner/KMS signs this hash to authorize a gasless grantP256Session().
+     */
+    buildP256GrantHash(params: Omit<GrantP256SessionParams, "ownerSig">): Promise<string>;
+    /**
+     * Query a P256 session key state (decodes the 8-field Session tuple).
+     * @param keyHash The keccak256 hash of (keyX, keyY) used as the on-chain session id.
+     */
+    getP256Session(account: string, keyHash: string): Promise<SessionInfo>;
+    /** Check if a P256 session is currently active. */
+    isP256SessionActive(account: string, keyX: string, keyY: string): Promise<boolean>;
+    /**
+     * Encode calldata for a P256/passkey session grant.
+     *
+     * - **With ownerSig** → `grantP256Session()` — for gasless/UserOp flows.
+     *   Owner signs the buildP256GrantHash() digest via KMS `sign-p256-grant-session`,
+     *   then the relayer calls `grantP256Session(account, keyX, keyY, cfg, ownerSig)` on-chain.
+     *   This is the ONLY path for ERC-4337 sponsored / gasless P256 grant flows.
+     *
+     * - **Without ownerSig** → `grantP256SessionDirect()` — **owner EOA direct-send only**.
+     *   Since v0.17.2 round 3, `grantP256SessionDirect` requires `msg.sender == ownerOf(account)`.
+     *   It does NOT accept `msg.sender == account` (removed in round 3 — confused-deputy fix).
+     *   Do NOT encode this for a UserOp callData; the EntryPoint is not the owner EOA.
+     */
+    encodeGrantP256Session(params: GrantP256SessionParams): string;
+    /** Encode calldata for revokeP256Session(). */
+    encodeRevokeP256Session(account: string, keyX: string, keyY: string): string;
+    /**
+     * Encode calldata for grantAgentSession().
+     * Must be called from the account (via UserOp or direct execute).
+     * The contract uses msg.sender as the account — no account param needed.
+     */
+    encodeGrantAgentSession(sessionKey: string, cfg: AgentSessionConfig): string;
+    /**
+     * Encode calldata for delegateSession() — sub-agent delegation.
+     * The sub-agent config must be a strict subset of the parent session's scope.
+     * Called by the parent session key (not the account owner).
+     * @param account The smart account under which the parent session was granted.
+     */
+    encodeDelegateSession(account: string, subKey: string, subCfg: AgentSessionConfig): string;
+    /** Encode calldata for revokeAgentSession(). */
+    encodeRevokeAgentSession(sessionKey: string): string;
+    /** Query agent session config + runtime state. */
+    getAgentSession(account: string, sessionKey: string): Promise<AgentSessionInfo>;
+    /** Check if an agent session is active (not expired, not revoked). */
+    isAgentSessionActive(account: string, sessionKey: string): Promise<boolean>;
+    /** Return the parent account of a delegated session key. */
+    getSessionKeyOwner(sessionKey: string): Promise<string>;
+    /** Return the parent key that delegated to subKey, or ZeroAddress if not delegated. */
+    getDelegatedBy(account: string, subKey: string): Promise<string>;
+}
+/**
+ * Pack a secp256k1 session key signature into the 106-byte UserOp.signature format.
+ *
+ * Layout: [0x08][account(20)][sessionKey(20)][r(32)][s(32)][v(1)]
+ *
+ * @param account - The AirAccount address (20 bytes, with or without 0x)
+ * @param sessionKey - The ephemeral EOA session key address (20 bytes)
+ * @param signature - 65-byte hex signature from KMS sign-grant-session (R||S||V)
+ * @returns 106-byte hex string (0x-prefixed) suitable as UserOp.signature
+ */
+declare function packSecp256k1SessionSignature(account: string, sessionKey: string, signature: string): string;
+/**
+ * Pack a P256 session key signature into the 149-byte UserOp.signature format.
+ *
+ * Layout: [0x08][account(20)][keyX(32)][keyY(32)][r(32)][s(32)]
+ *
+ * @param account - The AirAccount address (20 bytes)
+ * @param keyX - P256 public key X coordinate (32 bytes hex, without 0x)
+ * @param keyY - P256 public key Y coordinate (32 bytes hex, without 0x)
+ * @param signature - 64-byte hex signature from KMS sign-p256-grant-session (R||S, no V)
+ * @returns 149-byte hex string (0x-prefixed) suitable as UserOp.signature
+ */
+declare function packP256SessionSignature(account: string, keyX: string, keyY: string, signature: string): string;
+
+type TierLevel = 1 | 2 | 3;
+interface GuardState {
+    /** ETH daily limit in wei */
+    dailyLimit: bigint;
+    /** ETH already spent today in wei */
+    todaySpent: bigint;
+    /** ETH remaining for today in wei */
+    remaining: bigint;
+    /** Current tier based on spent amount */
+    currentTier: TierLevel;
+    /** Tier 1 max spend threshold in wei (single sig) */
+    tier1Limit: bigint;
+    /** Tier 2 max spend threshold in wei (dual sig) */
+    tier2Limit: bigint;
+    /** Minimum daily limit floor (cannot decrease below this) */
+    minDailyLimit: bigint;
+    /** Guard contract address */
+    guardAddress: string;
+}
+interface TokenGuardState {
+    token: string;
+    todaySpent: bigint;
+    dailyLimit: bigint;
+    remaining: bigint;
+    currentTier: TierLevel;
+    tier1Limit: bigint;
+    tier2Limit: bigint;
+}
+/**
+ * GuardStateReader — F6: read AAStarGlobalGuard spending state.
+ *
+ * Enables UI components to show:
+ *   - Daily spend progress bar
+ *   - Current required tier (T1/T2/T3) for next transaction
+ *   - Per-token limits and remaining allowances
+ */
+declare class GuardStateReader {
+    private readonly provider;
+    constructor(provider: PublicClient);
+    private accountContract;
+    private guardContract;
+    /**
+     * Read the full ETH guard state for an account.
+     * Returns null if the account has no guard (dailyLimit=0).
+     */
+    getGuardState(accountAddress: string): Promise<GuardState | null>;
+    /**
+     * Read per-token guard state.
+     * Returns null if the token is not configured on the guard.
+     */
+    getTokenGuardState(accountAddress: string, token: string): Promise<TokenGuardState | null>;
+    /**
+     * Determine the minimum tier required to send a given ETH amount.
+     * Useful for showing "this transfer needs 2 signatures" before submission.
+     */
+    requiredTierForAmount(accountAddress: string, amountWei: bigint): Promise<TierLevel>;
+    /**
+     * Check if a given algorithm ID is approved on the guard.
+     */
+    isAlgorithmApproved(accountAddress: string, algId: number): Promise<boolean>;
+}
+
+interface OapdConfig {
+    /** Account owner address */
+    owner: string;
+    /** DApp identifier — use the DApp's domain or contract address */
+    dappId: string;
+    /** Factory address (defaults to M7 Sepolia) */
+    factoryAddress?: string;
+    /**
+     * InitConfig for the OAPD account.
+     * Typically lower daily limits than the main account.
+     */
+    initConfig: {
+        guardians: [string, string, string];
+        dailyLimit: bigint;
+        approvedAlgIds: number[];
+        minDailyLimit: bigint;
+        initialTokens: string[];
+        initialTokenConfigs: Array<{
+            tier1Limit: bigint;
+            tier2Limit: bigint;
+            dailyLimit: bigint;
+        }>;
+    };
+}
+/**
+ * Compute the numeric salt for an OAPD address.
+ * salt = uint256(keccak256(abi.encodePacked(owner, dappId)))
+ */
+declare function computeOapdSalt(owner: string, dappId: string): bigint;
+/**
+ * Predict the counterfactual OAPD address without deploying.
+ * Uses the factory's getAddress() view function.
+ */
+declare function getOapdAddress(provider: PublicClient, config: OapdConfig): Promise<string>;
+/**
+ * Get the OAPD address and its ERC-7828 chain-qualified identifier.
+ */
+declare function getOapdAddressWithChainId(provider: PublicClient, config: OapdConfig): Promise<{
+    address: string;
+    chainQualified: string;
+}>;
+/**
+ * Check if an OAPD account has been deployed yet.
+ */
+declare function isOapdDeployed(provider: PublicClient, config: OapdConfig): Promise<boolean>;
+
+/** 4-byte selector of `executeUserOp((PackedUserOperation),bytes32)`. */
+declare const EXECUTE_USER_OP_SELECTOR: `0x${string}`;
+/** 4-byte selector of `execute(address,uint256,bytes)`. */
+declare const EXECUTE_SELECTOR: `0x${string}`;
+/** 4-byte selector of `executeBatch(address[],uint256[],bytes[])`. */
+declare const EXECUTE_BATCH_SELECTOR: `0x${string}`;
+/**
+ * Wrap inner `execute()` / `executeBatch()` callData with the `executeUserOp` selector so a
+ * guard-enabled (v0.17.2-beta.4) account routes the bundler UserOp through `executeUserOp`.
+ *
+ * Only `execute` / `executeBatch` may be wrapped — the account reverts
+ * `UnsupportedInnerSelector` for anything else (including a nested `executeUserOp`).
+ *
+ * Owner-direct (non-bundler) `execute()` does NOT need this; no-guard accounts can submit
+ * bare callData. Use this only when building a bundler UserOp for a guard-enabled account.
+ *
+ * @param innerCallData ABI-encoded `execute`/`executeBatch` calldata (0x-prefixed)
+ * @returns `executeUserOp.selector ++ innerCallData`
+ * @throws if `innerCallData` is not an `execute`/`executeBatch` call
+ */
+declare function wrapExecuteUserOp(innerCallData: string): string;
+/** True if callData is already wrapped with the executeUserOp selector. */
+declare function isExecuteUserOpWrapped(callData: string): boolean;
+
+declare const L2_TYPE: {
+    readonly OPTIMISM: 1;
+    readonly ARBITRUM: 2;
+};
+type L2Type = (typeof L2_TYPE)[keyof typeof L2_TYPE];
+interface PendingExit {
+    target: string;
+    value: bigint;
+    data: string;
+    proposedAt: bigint;
+    approvalBitmap: bigint;
+    guardians: [string, string, string];
+}
+/**
+ * A viem client capable of backing the ForceExit contract. A `PublicClient`
+ * alone enables the on-chain reads; a `WalletClient` (or the `{ public, wallet }`
+ * pair) is required for the state-changing `proposeForceExit`/`approveForceExit`/
+ * etc. transactions. This replaces the old `ethers.Provider | ethers.Signer`
+ * argument (provider = reads, signer = reads + writes).
+ */
+type ForceExitClient = PublicClient | WalletClient | {
+    public: PublicClient;
+    wallet: WalletClient;
+};
+/**
+ * ForceExitService — typed wrappers for ForceExitModule ERC-7579 emergency L2→L1 exit.
+ *
+ * Flow:
+ *   1. Owner installs module via account.installModule(2, forceExitModuleAddr, encodeOnInstall(L2_TYPE.OPTIMISM))
+ *   2. Any party calls proposeForceExit(target, value, data) to submit a bridge-out proposal
+ *   3. 2-of-3 guardians each call approveForceExit(account, guardianSig) within their window
+ *   4. Anyone calls executeForceExit(account) once threshold is met — triggers L2→L1 bridge call
+ *
+ * The module is an ERC-7579 Executor (moduleTypeId=2) — call installModule on the account, not here.
+ */
+declare class ForceExitService {
+    private readonly moduleAddress;
+    private readonly contract;
+    constructor(moduleAddress: string, client: ForceExitClient);
+    isInitialized(smartAccount: string): Promise<boolean>;
+    getPendingExit(account: string): Promise<PendingExit>;
+    getAccountL2Type(account: string): Promise<number>;
+    getApprovalThreshold(): Promise<number>;
+    getModuleVersion(): Promise<string>;
+    /**
+     * Encode onInstall calldata for installModule() call on the smart account.
+     * Must be submitted by the account owner, with moduleTypeId=2 (EXECUTOR).
+     *
+     * @param l2Type - L2_TYPE.OPTIMISM (1) or L2_TYPE.ARBITRUM (2)
+     * @example
+     * const calldata = forceExit.encodeOnInstall(L2_TYPE.OPTIMISM);
+     * // account.installModule(2, forceExitModuleAddress, calldata)
+     */
+    encodeOnInstall(l2Type: L2Type): string;
+    encodeOnUninstall(): string;
+    /**
+     * Encode calldata for proposeForceExit — the exit payload to bridge out of L2.
+     * `target` is the L2→L1 bridge contract; `data` is the bridge call payload.
+     */
+    encodeProposeForceExit(target: string, value: bigint, data: string): string;
+    /**
+     * Encode calldata for approveForceExit — guardian signs off on the pending proposal.
+     * `guardianSig` must be an EIP-191 personal_sign over the proposal hash.
+     */
+    encodeApproveForceExit(account: string, guardianSig: string): string;
+    encodeExecuteForceExit(account: string): string;
+    encodeCancelForceExit(account: string): string;
+    proposeForceExit(target: string, value: bigint, data: string): Promise<Hex>;
+    approveForceExit(account: string, guardianSig: string): Promise<Hex>;
+    executeForceExit(account: string): Promise<Hex>;
+    cancelForceExit(account: string): Promise<Hex>;
+}
+
+/**
+ * RECOVERY_THRESHOLD — number of distinct guardian approvals required to recover
+ * (or to cancel a recovery). The contract hard-codes `RECOVERY_THRESHOLD = 2`
+ * against a maximum of 3 guardians, i.e. a 2-of-3 social-recovery scheme.
+ *
+ * Source of truth: `AAStarAirAccountBase.RECOVERY_THRESHOLD` (internal constant).
+ */
+declare const RECOVERY_THRESHOLD = 2;
+/**
+ * MAX_GUARDIANS — the account stores at most 3 guardians (packed slots 12-14).
+ * Source: `AAStarAirAccountBase.addGuardian` (`_guardianCount >= 3` reverts).
+ */
+declare const MAX_GUARDIANS = 3;
+/**
+ * RECOVERY_TIMELOCK_SECONDS — delay between `proposeRecovery` and the earliest
+ * `executeRecovery`. The contract hard-codes `RECOVERY_TIMELOCK = 2 days`
+ * (172800 seconds).
+ *
+ * NOTE: the prose in `docs/abi/capabilities.md` says "72h"; the deployed
+ * contract uses 2 days (48h). The on-chain constant is authoritative.
+ *
+ * Source of truth: `AAStarAirAccountBase.RECOVERY_TIMELOCK` (internal constant).
+ */
+declare const RECOVERY_TIMELOCK_SECONDS: bigint;
+/**
+ * Decoded view of the account's `activeRecovery()` struct (RecoveryProposal).
+ *
+ * On-chain layout (`AAStarAgentStorageLayout.RecoveryProposal`):
+ *   - newOwner            : proposed new owner (address(0) ⇒ no active recovery)
+ *   - proposedAt          : block.timestamp when the recovery was proposed
+ *   - approvalBitmap      : bit i set ⇒ guardian[i] approved (2-of-3 to execute)
+ *   - cancellationBitmap  : bit i set ⇒ guardian[i] voted to cancel (2-of-3 to cancel)
+ *
+ * The remaining fields are SDK-side conveniences derived from those values.
+ */
+interface ActiveRecovery {
+    /** Proposed new owner. `0x0000…0000` means there is no active recovery. */
+    newOwner: string;
+    /** `block.timestamp` at which the recovery was proposed (seconds). */
+    proposedAt: bigint;
+    /** Bitmap of guardian approvals (bit i ⇒ guardian[i] approved). */
+    approvalBitmap: bigint;
+    /** Bitmap of guardian cancel votes (bit i ⇒ guardian[i] voted to cancel). */
+    cancellationBitmap: bigint;
+    /** Number of distinct guardian approvals (popcount of `approvalBitmap`). */
+    approvalCount: number;
+    /** Number of distinct guardian cancel votes (popcount of `cancellationBitmap`). */
+    cancellationCount: number;
+    /** Earliest timestamp at which `executeRecovery` may succeed (`proposedAt + timelock`). */
+    executeAfter: bigint;
+    /** True when a recovery is currently active (`newOwner != address(0)`). */
+    isActive: boolean;
+}
+/**
+ * RecoveryService — typed wrappers for AirAccount's on-chain social / guardian
+ * recovery (capability F28). Unlike `ForceExitService` (an ERC-7579 module),
+ * these functions live directly on the account contract, so every encoded
+ * calldata below is meant to be submitted **to the account address itself**
+ * (via a direct tx or a UserOp).
+ *
+ * ## Threshold & timelock
+ * 2-of-3 guardians ({@link RECOVERY_THRESHOLD} of {@link MAX_GUARDIANS}), with a
+ * {@link RECOVERY_TIMELOCK_SECONDS} (2-day) delay before execution.
+ *
+ * ## Lifecycle & who-can-call
+ *   1. `addGuardian(guardian)` — **owner only**. Registers a guardian (max 3).
+ *   2. `proposeRecovery(newOwner)` — **any guardian**. Starts the timelock and
+ *      records the proposer's approval bit (counts as the first of 2 approvals).
+ *   3. `approveRecovery()` — **another guardian**. Sets its approval bit; once
+ *      2-of-3 approvals are reached the threshold is satisfied.
+ *   4. `executeRecovery()` — **anyone**, but only after the timelock has elapsed
+ *      AND the approval threshold is met. Rotates `owner` to `newOwner`.
+ *   5. `cancelRecovery()` — **guardians only** (2-of-3 votes). The owner cannot
+ *      cancel: a thief who stole the owner key must not be able to block a
+ *      legitimate recovery. Each guardian votes independently.
+ *   6. `removeGuardian(index, guardianSigs)` — **owner**, but additionally
+ *      requires >= {@link RECOVERY_THRESHOLD} guardian signatures over the
+ *      removal hash (and cannot drop below 2 guardians).
+ *
+ * Guardian signatures are domain-separated per operation (the contract hashes a
+ * per-op label such as "REMOVE_GUARDIAN") to prevent cross-operation replay.
+ *
+ * ## Re-proposing
+ * A new proposal reverts with `RecoveryAlreadyActive` while one is pending. The
+ * docs reference a `clearStaleRecovery()` helper, but that function is NOT
+ * present in the deployed V7 ABI/contract — a stale proposal must instead be
+ * cleared via guardian `cancelRecovery()` votes before re-proposing.
+ */
+declare class RecoveryService {
+    private readonly client;
+    /**
+     * @param client viem read client (was `ethers.Provider | ethers.Signer`). Only
+     *   on-chain reads are performed here; calldata encoders are pure and never
+     *   touch the client.
+     */
+    constructor(client: PublicClient);
+    /**
+     * Encode `addGuardian(guardian)` calldata. **Owner only.**
+     * Registers a recovery guardian; reverts once 3 guardians are set, or if the
+     * guardian is `address(0)`, the owner, or already registered.
+     */
+    encodeAddGuardian(guardian: string): string;
+    /**
+     * Encode `removeGuardian(index, guardianSigs)` calldata. **Owner only**, and
+     * requires >= {@link RECOVERY_THRESHOLD} guardian signatures over the removal
+     * hash. Cannot remove while a recovery is active, nor drop below 2 guardians.
+     *
+     * @param index        Guardian slot to remove (0-indexed).
+     * @param guardianSigs EIP-191 guardian signatures over the removal hash.
+     */
+    encodeRemoveGuardian(index: number, guardianSigs: string[]): string;
+    /**
+     * Encode `proposeRecovery(newOwner)` calldata. **Any guardian** may call.
+     * Starts the {@link RECOVERY_TIMELOCK_SECONDS} timelock and records the
+     * proposer's approval (1 of {@link RECOVERY_THRESHOLD}).
+     */
+    encodeProposeRecovery(newOwner: string): string;
+    /**
+     * Encode `approveRecovery()` calldata. **Another guardian** approves the
+     * active proposal, setting its bit in `approvalBitmap`.
+     */
+    encodeApproveRecovery(): string;
+    /**
+     * Encode `cancelRecovery()` calldata. **Guardians only** — each call is one
+     * vote; recovery is dropped once {@link RECOVERY_THRESHOLD} cancel votes are
+     * reached. The owner cannot cancel.
+     */
+    encodeCancelRecovery(): string;
+    /**
+     * Encode `executeRecovery()` calldata. **Anyone** may call, but it only
+     * succeeds once the timelock has elapsed and the approval threshold is met.
+     * Rotates the account owner to the proposed `newOwner`.
+     */
+    encodeExecuteRecovery(): string;
+    /**
+     * Read and decode the account's `activeRecovery()` struct.
+     * Returns derived `approvalCount`, `cancellationCount`, `executeAfter`, and
+     * `isActive` alongside the raw fields.
+     *
+     * @param account The AirAccount address to query.
+     */
+    getActiveRecovery(account: string): Promise<ActiveRecovery>;
+    /**
+     * Read the number of registered guardians via `guardianCount()`.
+     *
+     * @param account The AirAccount address to query.
+     */
+    getGuardianCount(account: string): Promise<number>;
+    /**
+     * Read the full guardian address list.
+     *
+     * The V7 account exposes positional `guardians(uint256 i)` (3 packed slots) plus
+     * `guardianCount()` — there is no single `getGuardians()` getter on the account
+     * (that exists only on `AirAccountDelegate`, the EIP-7702 path). This reads slots
+     * `0..guardianCount-1` and returns the non-zero guardian addresses.
+     *
+     * @param account The AirAccount address to query.
+     */
+    getGuardians(account: string): Promise<string[]>;
+}
+
+declare const AIR_ACCOUNT_DELEGATE_ADDRESS = "0x8603AAF6C3f07fdae810B323c95a198D796EC52E";
+interface DelegateInitParams {
+    /** Guardian 1 address */
+    guardian1: string;
+    /** EIP-712 acceptance signature from guardian 1 */
+    guardian1Sig: string;
+    /** Guardian 2 address */
+    guardian2: string;
+    /** EIP-712 acceptance signature from guardian 2 */
+    guardian2Sig: string;
+    /** Daily ETH spend limit in wei */
+    dailyLimit: bigint;
+}
+interface EIP7702Authorization {
+    /** Chain ID (e.g. 11155111 for Sepolia) */
+    chainId: number;
+    /** The delegation target — AirAccountDelegate singleton address */
+    address: string;
+    /** EOA nonce at time of signing */
+    nonce: bigint;
+    /** Signature over the EIP-7702 authorization hash (65 bytes, R||S||V) */
+    signature: string;
+}
+/**
+ * EIP7702DelegateService — Path A: SDK payload construction for AirAccountDelegate.
+ *
+ * Path A applies when the integrator controls the private key (KMS, server-side signer,
+ * embedded wallet). The EOA signs a SET_CODE authorization offline; the integrator's relay
+ * submits a Type-4 transaction to activate the delegation.
+ *
+ * This service does NOT submit transactions — it produces signed payloads for relay.
+ *
+ * Deployed address: AirAccountDelegate singleton at AIR_ACCOUNT_DELEGATE_ADDRESS (Sepolia).
+ * The user's EOA address does NOT change — only its bytecode pointer changes to 0xef0100||addr.
+ *
+ * Usage:
+ *   1. Build SET_CODE authorization payload (call signer.signAuthorization externally — viem)
+ *   2. Build initialize() calldata for the first UserOp / direct tx
+ *   3. Submit both via integrator's relay
+ */
+declare class EIP7702DelegateService {
+    private readonly delegateAddress;
+    /** Parsed ABI (loose viem `Abi` shape) used for encoding calldata and on-chain reads. */
+    private readonly abi;
+    /** Optional viem read client (was `ethers.Provider | ethers.Signer`). Required only for on-chain reads. */
+    private readonly client?;
+    constructor(delegateAddress?: string, client?: PublicClient);
+    /**
+     * Encode initialize() calldata for the first post-delegation UserOp.
+     * Must be the callData of a UserOp sent immediately after the SET_CODE delegation activates.
+     * Guardian acceptance sigs follow the same EIP-712 scheme as AirAccountV7 createAccount.
+     */
+    encodeInitialize(params: DelegateInitParams): string;
+    encodeExecute(dest: string, value: bigint, data: string): string;
+    encodeExecuteBatch(dests: string[], values: bigint[], datas: string[]): string;
+    /**
+     * Compute the EIP-7702 SET_CODE authorization hash that the EOA must sign.
+     *
+     * Hash = keccak256(0x05 || RLP([chainId, address, nonce]))
+     *
+     * This is the hash the private key signs to delegate code execution to
+     * AirAccountDelegate. Use this hash with your KMS sign-hash endpoint or
+     * local viem account.
+     *
+     * @param chainId - Target chain ID (11155111 for Sepolia)
+     * @param nonce - EOA's current transaction nonce
+     * @returns 32-byte hash (0x-prefixed) ready for signing
+     */
+    buildAuthorizationHash(chainId: number, nonce: bigint): string;
+    /**
+     * Build the full EIP-7702 authorization object for relay submission.
+     * The caller must sign `buildAuthorizationHash()` externally and pass the result here.
+     *
+     * @param chainId - Target chain ID
+     * @param nonce - EOA's current nonce
+     * @param signature - 65-byte ECDSA signature (R||S||V) over the authorization hash
+     */
+    buildAuthorization(chainId: number, nonce: bigint, signature: string): EIP7702Authorization;
+    /**
+     * Verify that a signature is a valid EIP-7702 authorization for the given EOA address.
+     * Recovers the signer from the authorization hash and checks it matches `eoa`.
+     *
+     * NOTE: now async — viem's `recoverAddress` is asynchronous (ethers' was sync).
+     */
+    verifyAuthorization(eoa: string, chainId: number, nonce: bigint, signature: string): Promise<boolean>;
+    isInitialized(eoa: string): Promise<boolean>;
+    getOwner(eoa: string): Promise<string>;
+    getGuardians(eoa: string): Promise<[string, string, string]>;
+}
+
+/** Timelock that must elapse after a proposal before executeWeightChange() succeeds (WEIGHT_CHANGE_TIMELOCK = 2 days). */
+declare const WEIGHT_CHANGE_TIMELOCK_SECONDS: number;
+/** Guardian approvals required to execute a pending weight change (WEIGHT_CHANGE_THRESHOLD = 2-of-3). */
+declare const WEIGHT_CHANGE_THRESHOLD = 2;
+/** A proposal expires this long after it is proposed; approvals/execution after expiry revert (WEIGHT_CHANGE_EXPIRY = 30 days). */
+declare const WEIGHT_CHANGE_EXPIRY_SECONDS: number;
+/**
+ * WeightConfig — the weighted multi-signature policy for an AAStarAirAccount (algId 0x07).
+ *
+ * Each signer type / guardian contributes its weight; a transaction is authorized when the
+ * summed weight of present signatures meets the relevant tier threshold. tier1 is the base
+ * (required, non-zero) threshold; tier2/tier3 gate higher-value operations and, when set,
+ * must be monotonically non-decreasing (tier1 <= tier2 <= tier3).
+ *
+ * Field order MUST match the on-chain struct exactly (see AAStarAirAccountV7.json):
+ * passkeyWeight, ecdsaWeight, blsWeight, guardian0Weight, guardian1Weight, guardian2Weight,
+ * _padding, tier1Threshold, tier2Threshold, tier3Threshold.
+ */
+interface WeightConfig {
+    /** Weight granted by a valid passkey (P256/WebAuthn) signature. */
+    passkeyWeight: number;
+    /** Weight granted by a valid ECDSA (secp256k1 owner) signature. */
+    ecdsaWeight: number;
+    /** Weight granted by a valid BLS signature. */
+    blsWeight: number;
+    /** Weight granted by guardian slot 0. */
+    guardian0Weight: number;
+    /** Weight granted by guardian slot 1. */
+    guardian1Weight: number;
+    /** Weight granted by guardian slot 2. */
+    guardian2Weight: number;
+    /** Reserved padding byte (storage packing); keep 0. */
+    _padding: number;
+    /** Base threshold; must be non-zero and strictly greater than every individual weight. */
+    tier1Threshold: number;
+    /** Tier-2 threshold (0 = disabled); when set must be >= tier1Threshold. */
+    tier2Threshold: number;
+    /** Tier-3 threshold (0 = disabled); when set requires tier2 set and must be >= tier2Threshold. */
+    tier3Threshold: number;
+}
+/** A pending weight-change proposal awaiting guardian approval + timelock. */
+interface PendingWeightChange {
+    /** The proposed new WeightConfig. */
+    proposed: WeightConfig;
+    /** Unix timestamp when the proposal was created; 0 means no active proposal. */
+    proposedAt: bigint;
+    /** Bitmap of guardian indices that have approved (bit i set => guardian i approved). */
+    approvalBitmap: bigint;
+}
+/**
+ * WeightedSignatureService — typed wrappers for AAStarAirAccount weighted-signature
+ * governance (algId 0x07).
+ *
+ * Governance model:
+ *   - setWeightConfig(config): OWNER only. Used for the first-time config and for
+ *     *strengthening* changes (no individual weight or tier threshold decreased).
+ *     Reverts WeakeningRequiresProposal-equivalent path is enforced by the contract:
+ *     a weakening passed here reverts; route weakenings through proposeWeightChange.
+ *     Also reverts if a proposal is already pending (WeightChangePending).
+ *   - proposeWeightChange(config): OWNER only. Required when the new config *weakens*
+ *     security (lowers any weight or threshold). Opens a guardian-approved proposal.
+ *   - approveWeightChange(): GUARDIAN only (any of the 3 guardian slots). Each guardian
+ *     may approve once; approvals are tracked in approvalBitmap.
+ *   - executeWeightChange(): ANYONE, but only succeeds once BOTH conditions hold:
+ *       (1) approvals >= WEIGHT_CHANGE_THRESHOLD (2-of-3 guardians), and
+ *       (2) WEIGHT_CHANGE_TIMELOCK (2 days) has elapsed since proposedAt.
+ *     A proposal also expires after WEIGHT_CHANGE_EXPIRY (30 days).
+ *   - cancelWeightChange(): OWNER or any GUARDIAN may cancel a pending proposal.
+ *
+ * Unlike ForceExitService (an ERC-7579 module), these calls target the ACCOUNT itself.
+ * Construct with the account address; encode* methods return calldata for a UserOp or
+ * direct tx, and reads use the contract directly.
+ */
+declare class WeightedSignatureService {
+    private readonly accountAddress;
+    private readonly client;
+    private readonly address;
+    constructor(accountAddress: string, client: PublicClient);
+    /** Read the account's current active WeightConfig. */
+    getWeightConfig(): Promise<WeightConfig>;
+    /**
+     * Read the pending weight-change proposal. When `proposedAt === 0n` there is no
+     * active proposal (the returned `proposed` config will be all zeros).
+     */
+    getPendingWeightChange(): Promise<PendingWeightChange>;
+    /**
+     * Encode setWeightConfig calldata. OWNER only; for first-time setup or strengthening.
+     * Weakening an existing config must go through encodeProposeWeightChange instead.
+     */
+    encodeSetWeightConfig(config: WeightConfig): Hex;
+    /**
+     * Encode proposeWeightChange calldata. OWNER only; opens a guardian-governed proposal
+     * (required for any weakening). Subject to 2-of-3 approval + 2-day timelock before execute.
+     */
+    encodeProposeWeightChange(config: WeightConfig): Hex;
+    /** Encode approveWeightChange calldata. GUARDIAN only; each guardian may approve once. */
+    encodeApproveWeightChange(): Hex;
+    /** Encode cancelWeightChange calldata. OWNER or any GUARDIAN may cancel a pending proposal. */
+    encodeCancelWeightChange(): Hex;
+    /**
+     * Encode executeWeightChange calldata. Callable by anyone, but only succeeds once the
+     * threshold (2-of-3) and timelock (2 days) are both satisfied and the proposal has not expired.
+     */
+    encodeExecuteWeightChange(): Hex;
+}
+
+interface CreateAgentAccountParams {
+    /** The agent's own signing key (EOA controlled by the agent runtime / KMS). */
+    agentKey: string;
+    /** ERC-8004-style agent identifier (bytes32) binding this account to an off-chain identity. */
+    agentId: string;
+    /** The human guardian (guardian2) co-owning the agent account for recovery. */
+    guardian2: string;
+    /** Guardian2's acceptance signature over the creation hash (EIP-191). */
+    guardian2Sig: string;
+    /** The agent key's acceptance signature over the creation hash (EIP-191). */
+    agentKeySig: string;
+    /** Unix timestamp (uint48) after which the signatures are rejected. */
+    deadline: bigint | number;
+    /** Daily transfer limit in wei (on-chain guard enforcement; V7 requires > 0). */
+    dailyLimit: bigint;
+}
+/**
+ * AgentRegistryService — typed wrappers for the AAStar AgentRegistry contract plus the
+ * AAStarAirAccountFactoryV7 agent-account creation helpers.
+ *
+ * **Two contracts, two responsibilities:**
+ *
+ * 1. AgentRegistry (constructor `registryAddress`) — the canonical map of agent wallet →
+ *    human owner used by SuperPaymaster to authorise gasless sponsorship. The factory calls
+ *    `markValid`/registers the agent at deployment; humans manage the binding afterwards via
+ *    `registerAgent` / `revokeAgent` / `deregisterAgent`.
+ *
+ * 2. AAStarAirAccountFactoryV7 — deploys an agent-owned AirAccount. `encodeCreateAgentAccount`
+ *    targets the factory (NOT the registry); `getAgentAccountAddress` predicts the CREATE2
+ *    address before deployment.
+ *
+ * All `encode*` methods return ABI-encoded calldata ready for a UserOp (gasless) or a direct
+ * owner transaction. Read methods require a viem `PublicClient`.
+ */
+declare class AgentRegistryService {
+    private readonly registryAddress;
+    private readonly client;
+    /**
+     * @param client          viem PublicClient for on-chain reads (e.g. `ethereum.getProvider()`).
+     * @param registryAddress deployed AgentRegistry contract address.
+     */
+    constructor(client: PublicClient, registryAddress: string);
+    /** Encode `account.execute(registry, 0, registerAgent(agentWallet, agentWalletSig))`. */
+    encodeRegisterAgentViaAccount(agentWallet: string, agentWalletSig: string): string;
+    /** Encode `account.execute(registry, 0, revokeAgent(agentWallet))`. */
+    encodeRevokeAgentViaAccount(agentWallet: string): string;
+    /**
+     * Encode calldata for `registerAgent(agentWallet, agentWalletSig)`.
+     *
+     * Binds `agentWallet` to the caller (the human owner). `agentWalletSig` must be the agent
+     * wallet's EIP-191 signature proving control of the key. Reverts with
+     * `SelfRegistrationForbidden` if the caller registers itself, or `AgentAlreadyRegistered`
+     * if the wallet is already bound.
+     */
+    encodeRegisterAgent(agentWallet: string, agentWalletSig: string): string;
+    /**
+     * Encode calldata for `revokeAgent(agentWallet)`.
+     *
+     * Owner-initiated revocation of a previously registered agent wallet. Caller must be the
+     * agent's human owner (else `NotAgentOwner`).
+     */
+    encodeRevokeAgent(agentWallet: string): string;
+    /**
+     * Encode calldata for `deregisterAgent(agentWallet)`.
+     *
+     * Removes the agent wallet from the registry (full deregistration, distinct from the
+     * lighter-weight `revokeAgent`). Caller must be the agent's human owner.
+     */
+    encodeDeregisterAgent(agentWallet: string): string;
+    /** Whether `agentWallet` is currently registered in the registry. */
+    isRegisteredAgent(agentWallet: string): Promise<boolean>;
+    /** Whether `account` has been marked valid (e.g. an AirAccount minted by the bound factory). */
+    isValidAccount(account: string): Promise<boolean>;
+    /** The human owner bound to `agentWallet` (ZeroAddress if unregistered). */
+    getHumanOwner(agentWallet: string): Promise<string>;
+    /** Number of agents registered under `owner`. */
+    getAgentCount(owner: string): Promise<bigint>;
+    /** The agent wallet at `index` in `owner`'s agent list. */
+    getAgentByIndex(owner: string, index: bigint | number): Promise<string>;
+    /** Full list of agent wallets registered under `humanOwner`. */
+    getAgents(humanOwner: string): Promise<string[]>;
+    /**
+     * Paginated slice of `owner`'s agent wallets: `count` entries starting at `start`.
+     * The contract clamps `count` to the remaining length, so the returned array may be shorter.
+     */
+    getAgentsPage(owner: string, start: bigint | number, count: bigint | number): Promise<string[]>;
+    /** Raw `agentWalletOwner` mapping read (agentWallet → owner). */
+    agentWalletOwner(agentWallet: string): Promise<string>;
+    /** Raw `ownerAgents` array read (owner, index → agentWallet). */
+    ownerAgents(owner: string, index: bigint | number): Promise<string>;
+    /**
+     * Encode calldata for the factory's `createAgentAccount(...)`.
+     *
+     * Targets the AAStarAirAccountFactoryV7, NOT the AgentRegistry. The factory deploys the agent
+     * AirAccount and registers it in the bound AgentRegistry in one transaction. Submit this
+     * calldata to the factory address (direct tx or via a relayer).
+     */
+    encodeCreateAgentAccount(params: CreateAgentAccountParams): string;
+    /**
+     * Encode calldata for the factory's `setAgentRegistry(_agentRegistry)` (factory-admin only).
+     */
+    encodeSetAgentRegistry(agentRegistry: string): string;
+    /**
+     * Predict the CREATE2 address of an agent account via the factory's `getAgentAddress(...)`.
+     *
+     * @param factoryAddress AAStarAirAccountFactoryV7 address.
+     * @param humanOwner     the human guardian/owner co-owning the agent account.
+     * @param agentKey       the agent's signing key.
+     * @param agentId        the bytes32 agent identifier.
+     */
+    getAgentAccountAddress(factoryAddress: string, humanOwner: string, agentKey: string, agentId: string): Promise<string>;
+    /** Read the AgentRegistry address currently bound to the factory. */
+    getFactoryAgentRegistry(factoryAddress: string): Promise<string>;
+}
+
+declare const ERC8004_ADDRESSES: {
+    readonly mainnet: {
+        readonly identityRegistry: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
+        readonly reputationRegistry: "0x8004BAa17C55a88189AE136b182e5fdA19dE9b63";
+        readonly validationRegistry: "0x8004Cc8439f36fd5F9F049D9fF86523Df6dAAB58";
+    };
+    readonly testnet: {
+        readonly identityRegistry: "0x8004A818BFB912233c491871b3d84c89A494BD9e";
+        readonly reputationRegistry: "0x8004B663056A597Dffe9eCcC1965A193B7388713";
+        readonly validationRegistry: "0x8004Cb1BF31DAf7788923b405b754f57acEB4272";
+    };
+};
+declare function erc8004AddressesForChain(chainId: number): (typeof ERC8004_ADDRESSES)["mainnet"] | (typeof ERC8004_ADDRESSES)["testnet"];
+interface SetAgentWalletParams {
+    agentId: bigint;
+    agentWallet: string;
+    /** AAStar AgentRegistry contract address (SuperPaymaster-facing, NOT the official ERC-8004 registry) */
+    agentRegistry: string;
+    /** Signature from the agent wallet proving ownership */
+    agentWalletSig: string;
+}
+interface MintAgentIdentityParams {
+    /** Must be the official ERC-8004 identity registry for this chain */
+    identityRegistry: string;
+    /** Agent metadata URI (ERC-721 tokenURI) */
+    agentURI: string;
+}
+interface BindERC8004AgentWalletParams {
+    /** Must be the official ERC-8004 identity registry for this chain */
+    identityRegistry: string;
+    agentId: bigint;
+    agentWallet: string;
+    /** Unix timestamp — signature becomes invalid after this deadline */
+    deadline: bigint;
+    /** Signature authorising the wallet binding, signed by the identity registry's expected signer */
+    signature: string;
+}
+interface SubmitAgentReputationParams {
+    /** Must be the official ERC-8004 reputation registry for this chain */
+    reputationRegistry: string;
+    agentId: bigint;
+    value: bigint;
+    valueDecimals: number;
+    tag1: string;
+    tag2: string;
+    endpoint: string;
+    feedbackURI: string;
+    feedbackHash: string;
+}
+interface QueryAgentReputationParams {
+    /** Must be the official ERC-8004 reputation registry for this chain */
+    reputationRegistry: string;
+    agentId: bigint;
+    clientAddresses: string[];
+    tag1: string;
+    tag2: string;
+}
+interface AgentReputationSummary {
+    count: bigint;
+    summaryValue: bigint;
+    summaryDecimals: number;
+}
+/**
+ * ERC8004Service — TypeScript wrappers for AirAccount's ERC-8004 "Trustless Agents" functions.
+ *
+ * **Two distinct registration paths:**
+ *
+ * 1. `encodeSetAgentWallet` — AAStar/SuperPaymaster path.
+ *    Registers the agent wallet in the AAStar AgentRegistry contract. Use this when you want
+ *    SuperPaymaster to recognise the agent for gasless sponsorship. The `agentRegistry` argument
+ *    is the deployed AgentRegistry address, NOT the official ERC-8004 IdentityRegistry.
+ *
+ * 2. `encodeMintAgentIdentity` + `encodeBindERC8004AgentWallet` — official ERC-8004 path.
+ *    Mints an ERC-721 identity NFT in the official ERC-8004 IdentityRegistry and binds an
+ *    execution wallet to it. The registry address MUST be from `erc8004AddressesForChain()`.
+ *    These calls revert on-chain if the wrong registry address is supplied.
+ *
+ * All `encode*` methods return ABI-encoded calldata ready to be submitted via UserOp (gasless)
+ * or a direct owner transaction. The calldata targets the AirAccount address — the account's
+ * fallback delegates to AirAccountExtension for these selectors.
+ */
+declare class ERC8004Service {
+    private readonly abi;
+    private readonly provider?;
+    constructor(provider?: PublicClient);
+    /**
+     * Build a read-only viem contract bound to the account address. The ABI is loaded from
+     * human-readable signatures via `parseAbi` (loose `Abi`), so `read` methods are indexed by
+     * name and return `unknown` — cast at the call site. Mirrors the dynamic surface that
+     * `ethers.Contract` previously exposed. Caller must ensure `this.provider` is set.
+     */
+    private contractAt;
+    /**
+     * Encode calldata for `setAgentWallet`.
+     *
+     * Registers `agentWallet` in the AAStar AgentRegistry (SuperPaymaster-facing). This is the
+     * correct path when the goal is SuperPaymaster gasless sponsorship for the agent.
+     *
+     * **Not** a call to the official ERC-8004 IdentityRegistry. Use `encodeMintAgentIdentity`
+     * + `encodeBindERC8004AgentWallet` for the ERC-8004 standard path.
+     *
+     * Callable: owner EOA direct tx OR via UserOp (gasless).
+     */
+    encodeSetAgentWallet(params: SetAgentWalletParams): string;
+    /**
+     * Encode calldata for `mintAgentIdentity`.
+     *
+     * Mints an ERC-721 agent identity NFT in the official ERC-8004 IdentityRegistry and returns
+     * the new `agentId` (decoded from the tx receipt). The `identityRegistry` must be
+     * `erc8004AddressesForChain(chainId).identityRegistry` — the contract reverts otherwise.
+     *
+     * Callable: owner EOA direct tx OR via UserOp (gasless).
+     */
+    encodeMintAgentIdentity(params: MintAgentIdentityParams): string;
+    /**
+     * Encode calldata for `bindERC8004AgentWallet`.
+     *
+     * Binds an execution wallet to an existing ERC-8004 agent identity NFT. Requires a
+     * deadline-bounded signature from the expected signer (see the IdentityRegistry contract).
+     * The `identityRegistry` must be the official chain-specific address.
+     *
+     * Callable: owner EOA direct tx OR via UserOp (gasless).
+     */
+    encodeBindERC8004AgentWallet(params: BindERC8004AgentWalletParams): string;
+    /**
+     * Encode calldata for `submitAgentReputation`.
+     *
+     * Submits a reputation feedback entry to the official ERC-8004 ReputationRegistry.
+     * `reputationRegistry` must be `erc8004AddressesForChain(chainId).reputationRegistry`.
+     *
+     * Callable: owner EOA direct tx OR via UserOp (gasless).
+     */
+    encodeSubmitAgentReputation(params: SubmitAgentReputationParams): string;
+    /**
+     * Query aggregated reputation for an agent from the official ERC-8004 ReputationRegistry.
+     * Returns `null` when no provider was supplied at construction.
+     */
+    queryAgentReputation(accountAddress: string, params: QueryAgentReputationParams): Promise<AgentReputationSummary>;
+    /**
+     * Encode calldata for `queryAgentReputation` (for static-call or eth_call without a signer).
+     */
+    encodeQueryAgentReputation(params: QueryAgentReputationParams): string;
+    /**
+     * Read the agentExtension implementation address from a deployed AirAccount.
+     */
+    getAgentExtensionAddress(accountAddress: string): Promise<string>;
+}
+
+/**
+ * Request to mint a new agent key under an existing human key.
+ *
+ * WebAuthn-gated: the human approves the mint with a one-time WebAuthn ceremony
+ * (preferred) or a Legacy passkey assertion. The challenge is obtained via
+ * {@link KmsManager.beginAuthentication} (generic, purpose="authentication") —
+ * the caller supplies the resulting assertion here.
+ */
+interface KmsCreateAgentKeyRequest {
+    humanKeyId: string;
+    label?: string;
+    webAuthnAssertion?: WebAuthnAssertion;
+    passkeyAssertion?: LegacyPasskeyAssertion;
+}
+interface KmsCreateAgentKeyResponse {
+    keyId: string;
+    agentAddress: string;
+    derivationPath: string;
+    agentCredential: string;
+    expiresAt: number;
+}
+/**
+ * Request to sign a userOpHash with an agent key, authenticated by the agent's
+ * TEE-JWT credential (Bearer). Used for gasless ERC-4337 sponsorship.
+ */
+interface KmsSignAgentRequest {
+    keyId: string;
+    payload: string;
+    algorithm?: string;
+    accountAddress: string;
+}
+interface KmsSignAgentResponse {
+    keyId: string;
+    agentAddress: string;
+    /** Hex 106-byte signature: [0x08][account(20)][key(20)][r(32)][s(32)][v(1)]. */
+    signature: string;
+}
+/**
+ * Request to refresh (re-mint) an agent's TEE-JWT credential before it expires.
+ *
+ * Authenticated with the existing (still-valid) credential via Bearer JWT, plus
+ * a WebAuthn / Legacy passkey assertion from the human key owner.
+ */
+interface KmsRefreshAgentCredentialRequest {
+    keyId: string;
+    webAuthnAssertion?: WebAuthnAssertion;
+    passkeyAssertion?: LegacyPasskeyAssertion;
+}
+/**
+ * The server response shape is not strictly documented; this models the fields
+ * the SDK relies on. `keyId` is echoed back optionally.
+ */
+interface KmsRefreshAgentCredentialResponse {
+    keyId?: string;
+    agentCredential: string;
+    expiresAt: number;
+}
+/**
+ * Request to revoke an agent's credential (WebAuthn-gated).
+ *
+ * The challenge is obtained via {@link KmsManager.beginAuthentication} (generic,
+ * purpose="authentication"); the caller supplies the resulting assertion here.
+ */
+interface KmsRevokeAgentCredentialRequest {
+    keyId: string;
+    webAuthnAssertion?: WebAuthnAssertion;
+    passkeyAssertion?: LegacyPasskeyAssertion;
+}
+interface KmsRevokeAgentCredentialResponse {
+    success: boolean;
+    revokedAt: number;
+}
+/**
+ * Agent-key lifecycle service for the AAStar TEE KMS (v0.20.0).
+ *
+ * An "agent key" is a TEE-JWT credential minted under a human key, used for
+ * gasless ERC-4337 sponsorship without re-prompting the human for each signature.
+ * Lifecycle:
+ *   1. {@link createAgentKey}        — human mints the agent key (WebAuthn-gated)
+ *   2. {@link signAgent}             — agent signs userOpHashes (Bearer JWT auth)
+ *   3. {@link refreshAgentCredential}— re-mint before expiry (Bearer JWT + WebAuthn)
+ *   4. {@link revokeAgentCredential} — human revokes the agent key (WebAuthn-gated)
+ *
+ * Wraps a shared {@link KmsHttpClient} — obtain it via {@link KmsManager.httpClient}
+ * so this service reuses the same connection config and auth headers.
+ */
+declare class KmsAgentService {
+    private readonly http;
+    constructor(http: KmsHttpClient);
+    /**
+     * Mint a new agent key under an existing human key (WebAuthn-gated).
+     *
+     * The WebAuthn challenge is obtained from a generic
+     * {@link KmsManager.beginAuthentication} ceremony (purpose="authentication");
+     * the caller supplies the resulting assertion in the request.
+     */
+    createAgentKey(params: KmsCreateAgentKeyRequest): Promise<KmsCreateAgentKeyResponse>;
+    /**
+     * Sign a userOpHash with an agent key, authenticated by the agent's TEE-JWT
+     * credential (`jwt`, the `agentCredential` from {@link createAgentKey}).
+     * Returns the 106-byte packed signature for ERC-4337 sponsorship.
+     */
+    signAgent(params: KmsSignAgentRequest, jwt: string): Promise<KmsSignAgentResponse>;
+    /**
+     * Refresh (re-mint) an agent credential before it expires. Authenticated with
+     * the existing credential (`jwt`, Bearer) plus a human WebAuthn / passkey
+     * assertion in the request.
+     */
+    refreshAgentCredential(params: KmsRefreshAgentCredentialRequest, jwt: string): Promise<KmsRefreshAgentCredentialResponse>;
+    /**
+     * Revoke an agent's credential (WebAuthn-gated).
+     *
+     * The WebAuthn challenge is obtained from a generic
+     * {@link KmsManager.beginAuthentication} ceremony (purpose="authentication");
+     * the caller supplies the resulting assertion in the request.
+     */
+    revokeAgentCredential(params: KmsRevokeAgentCredentialRequest): Promise<KmsRevokeAgentCredentialResponse>;
+    /** Mint an agent key, running the challenge-binding ceremony internally. */
+    createAgentKeyWithCeremony(params: Omit<KmsCreateAgentKeyRequest, "webAuthnAssertion" | "passkeyAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsCreateAgentKeyResponse>;
+    /**
+     * Refresh an agent credential, running the challenge-binding ceremony
+     * internally. `humanKeyId` is the owning human key challenged by the ceremony
+     * (distinct from the agent `keyId` in `params`); `jwt` is the existing credential.
+     */
+    refreshAgentCredentialWithCeremony(params: Omit<KmsRefreshAgentCredentialRequest, "webAuthnAssertion" | "passkeyAssertion">, humanKeyId: string, jwt: string, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsRefreshAgentCredentialResponse>;
+    /**
+     * Revoke an agent credential, running the challenge-binding ceremony internally.
+     * `humanKeyId` is the owning human key challenged by the ceremony (distinct from
+     * the agent `keyId` in `params`).
+     */
+    revokeAgentCredentialWithCeremony(params: Omit<KmsRevokeAgentCredentialRequest, "webAuthnAssertion" | "passkeyAssertion">, humanKeyId: string, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<KmsRevokeAgentCredentialResponse>;
+}
+
+interface CreateP256SessionKeyRequest {
+    /** Human (root) key under which the session key is minted. */
+    humanKeyId: string;
+    /** Optional human-readable label for the session key. */
+    label?: string;
+    /**
+     * One-time WebAuthn assertion gating creation. The challenge comes from a
+     * generic {@link KmsManager.beginAuthentication} ceremony — the caller runs
+     * the ceremony and supplies the resulting assertion here.
+     */
+    webAuthnAssertion?: WebAuthnAssertion;
+}
+interface CreateP256SessionKeyResponse {
+    keyId: string;
+    pubKeyX: string;
+    pubKeyY: string;
+    algorithm: string;
+    agentCredential: string;
+    expiresAt: number;
+}
+interface SignP256UserOpRequest {
+    keyId: string;
+    payload: string;
+    accountAddress: string;
+}
+interface SignP256UserOpResponse {
+    keyId: string;
+    pubKeyX: string;
+    pubKeyY: string;
+    /**
+     * 149-byte P256 session-key wire format (hex):
+     * [0x08][account(20)][keyX(32)][keyY(32)][r(32)][s(32)].
+     */
+    signature: string;
+}
+interface RevokeP256SessionKeyRequest {
+    keyId: string;
+    /**
+     * One-time WebAuthn assertion gating revocation. The challenge comes from a
+     * generic {@link KmsManager.beginAuthentication} ceremony — the caller runs
+     * the ceremony and supplies the resulting assertion here.
+     */
+    webAuthnAssertion?: WebAuthnAssertion;
+}
+interface RevokeP256SessionKeyResponse {
+    success: boolean;
+    revokedAt: number;
+}
+/**
+ * Manages the lifecycle of a P-256 session key minted under a human key for
+ * ERC-4337 UserOp signing (AAStar TEE KMS v0.20.0).
+ *
+ * A session key is created under a root (human) key, used to sign UserOps via a
+ * TEE-issued bearer JWT (the `agentCredential`), and eventually revoked. The
+ * per-UserOp signature is the 149-byte P256 session-key wire format.
+ *
+ * Relationship to {@link KmsManager.signP256GrantSession}: that method signs the
+ * GRANT_P256_SESSION_V2 authorization needed to *install* this key on-chain
+ * (granting the session key its on-chain scope/policies). This service instead
+ * manages the session key's own lifecycle (create / sign / revoke) once granted.
+ *
+ * Create and revoke are WebAuthn-gated: the challenge originates from a generic
+ * {@link KmsManager.beginAuthentication} ceremony and the caller supplies the
+ * resulting assertion. Per-UserOp signing authenticates with the bearer JWT.
+ *
+ * Wraps a shared {@link KmsHttpClient} — pass `KmsManager.httpClient`.
+ */
+declare class KmsSessionService {
+    private readonly http;
+    constructor(http: KmsHttpClient);
+    /**
+     * Create a P-256 session key under a human key (WebAuthn-gated).
+     *
+     * `POST /kms/create-p256-session-key`. The `webAuthnAssertion` challenge comes
+     * from a generic {@link KmsManager.beginAuthentication} ceremony supplied by
+     * the caller. Returns the session key's public key plus an `agentCredential`
+     * JWT used to authenticate subsequent {@link signP256UserOp} calls.
+     */
+    createP256SessionKey(params: CreateP256SessionKeyRequest): Promise<CreateP256SessionKeyResponse>;
+    /**
+     * Sign an ERC-4337 UserOp hash with a P-256 session key (Bearer JWT auth).
+     *
+     * `POST /kms/sign-p256-user-op`, authenticated with the `agentCredential` JWT
+     * returned by {@link createP256SessionKey}. Returns the 149-byte P256
+     * session-key wire-format signature.
+     */
+    signP256UserOp(params: SignP256UserOpRequest, jwt: string): Promise<SignP256UserOpResponse>;
+    /**
+     * Revoke a P-256 session key (WebAuthn-gated, idempotent).
+     *
+     * `POST /kms/revoke-p256-session-key`. The `webAuthnAssertion` challenge comes
+     * from a generic {@link KmsManager.beginAuthentication} ceremony supplied by
+     * the caller. Idempotent: revoking an already-revoked key still resolves.
+     */
+    revokeP256SessionKey(params: RevokeP256SessionKeyRequest): Promise<RevokeP256SessionKeyResponse>;
+    /** Create a P-256 session key, running the challenge-binding ceremony internally. */
+    createP256SessionKeyWithCeremony(params: Omit<CreateP256SessionKeyRequest, "webAuthnAssertion">, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<CreateP256SessionKeyResponse>;
+    /**
+     * Revoke a P-256 session key, running the challenge-binding ceremony internally.
+     * `humanKeyId` is the owning human key challenged by the ceremony (distinct from
+     * the session `keyId` in `params`).
+     */
+    revokeP256SessionKeyWithCeremony(params: Omit<RevokeP256SessionKeyRequest, "webAuthnAssertion">, humanKeyId: string, signer: PasskeyCeremonySigner, options?: Omit<RunCeremonyOptions, "signer">): Promise<RevokeP256SessionKeyResponse>;
+}
+
+type KmsPaymentAuth = {
+    jwt: string;
+} | {
+    webAuthnAssertion: WebAuthnAssertion;
+};
+/** Shared signature response for all payment signing endpoints. */
+interface KmsPaymentSignatureResponse {
+    keyId: string;
+    signature: string;
+}
+interface KmsSignMicropaymentVoucherRequest {
+    keyId: string;
+    hdPath?: string;
+    chainId: number;
+    verifyingContract: string;
+    channelId: string;
+    cumulativeAmount: string;
+}
+interface KmsSignGTokenAuthorizationRequest {
+    keyId: string;
+    hdPath?: string;
+    chainId: number;
+    gTokenAddress: string;
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+interface KmsSignX402PaymentRequest {
+    keyId: string;
+    hdPath?: string;
+    chainId: number;
+    verifyingContract: string;
+    paymentId: string;
+    amount: string;
+    recipient: string;
+    deadline: string;
+}
+/**
+ * Convenience signers for SuperPaymaster payment flows (v0.20.0 P2).
+ *
+ * Each method maps to a fixed EIP-712 domain + type that the KMS builds host-side
+ * and signs inside the TEE; the SDK only forwards the structured parameters. Every
+ * endpoint accepts EITHER a one-time `webAuthnAssertion` in the body OR an agent
+ * Bearer JWT — see {@link KmsPaymentAuth}.
+ *
+ * Wraps a shared {@link KmsHttpClient}; reuse the same instance across the agent /
+ * session / payment / monitor services.
+ */
+declare class KmsPaymentSigner {
+    private readonly http;
+    constructor(http: KmsHttpClient);
+    /**
+     * Dispatch a payment-signing request with the chosen auth mode.
+     * JWT auth uses `postWithBearer`; WebAuthn auth merges the assertion into the body.
+     */
+    private signWithAuth;
+    /**
+     * Sign a MicroPaymentChannel voucher (cumulative-amount EIP-712 message)
+     * via `POST /kms/SignMicropaymentVoucher`.
+     */
+    signMicropaymentVoucher(params: KmsSignMicropaymentVoucherRequest, auth: KmsPaymentAuth): Promise<KmsPaymentSignatureResponse>;
+    /**
+     * Sign an EIP-3009 TransferWithAuthorization for a GToken transfer
+     * via `POST /kms/SignGTokenAuthorization`. `from` MUST equal the derived address.
+     */
+    signGTokenAuthorization(params: KmsSignGTokenAuthorizationRequest, auth: KmsPaymentAuth): Promise<KmsPaymentSignatureResponse>;
+    /**
+     * Sign an x402 payment authorization via `POST /kms/SignX402Payment`.
+     */
+    signX402Payment(params: KmsSignX402PaymentRequest, auth: KmsPaymentAuth): Promise<KmsPaymentSignatureResponse>;
+}
+
+/**
+ * Liveness probe response. Returned by `GET /health` without auth — works even
+ * when the SDK's KMS feature flag is off.
+ */
+interface KmsHealthResponse {
+    status: string;
+    service?: string;
+    ta_mode?: string;
+    version?: string;
+}
+/**
+ * Version / capability descriptor. Returned by `GET /version` without auth.
+ * Extra fields are passed through.
+ */
+interface KmsVersionResponse {
+    version?: string;
+    ta_mode?: string;
+    endpoints?: string[];
+    [k: string]: unknown;
+}
+/**
+ * KMS request-queue health, including circuit-breaker state. Useful for
+ * back-pressure decisions before submitting signing operations.
+ */
+interface KmsQueueStatusResponse {
+    queue_depth: number;
+    estimated_wait_seconds: number;
+    circuit_breaker_open: boolean;
+    consecutive_failures: number;
+}
+/**
+ * RPMB anti-rollback monotonic counter (diagnostic, v0.20.0). The exact shape
+ * is undocumented; the known `counter` field is surfaced and all other fields
+ * are passed through.
+ */
+interface KmsRollbackCounterResponse {
+    counter?: number;
+    [k: string]: unknown;
+}
+/**
+ * Machine-readable runtime statistics (v0.20.0). Pass-through; the response is
+ * not strongly typed. Known top-level fields:
+ *   - `wallets`  — wallet / key counts
+ *   - `tx`       — transaction / signing counts
+ *   - `queue`    — queue depth and timing metrics
+ *   - `warnings` — active operational warnings
+ */
+interface KmsStatsResponse {
+    [k: string]: unknown;
+}
+/** `GET /attestation` evidence bound to a caller nonce (#37). */
+interface KmsAttestationResponse {
+    schema?: string;
+    nonce?: string;
+    ta_uuid?: string;
+    ta_measurement?: string;
+    signature?: string;
+    attest_pubkey_exp?: string;
+    attest_pubkey_mod?: string;
+    sig_alg?: number;
+    ree_time_secs?: number;
+    trust_root?: string;
+    [k: string]: unknown;
+}
+/** `GET /.well-known/attestation-measurements.json` — Ed25519-signed manifest (#12). */
+interface KmsAttestationManifestResponse {
+    body?: Record<string, unknown>;
+    publisher_key?: string;
+    signature?: string;
+    [k: string]: unknown;
+}
+/** `GET /.well-known/attestation-measurements-proof.json` — Sigsum proof sidecar (#87). */
+interface KmsAttestationProofResponse {
+    proof?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/**
+ * Response of the destructive operator-only purge action (v0.20.0).
+ * Pass-through; the response shape is not strongly typed.
+ */
+interface KmsPurgeKeyResponse {
+    [k: string]: unknown;
+}
+/**
+ * Infrastructure monitoring + operator admin surface for the AAStar TEE KMS
+ * (v0.20.0, kms.aastar.io).
+ *
+ * Wraps a shared {@link KmsHttpClient}. Liveness probes (`health`, `version`)
+ * intentionally bypass the `enabled` gate so they work even when the SDK's KMS
+ * feature flag is off; every other method calls `ensureEnabled()` first.
+ */
+declare class KmsMonitorService {
+    private readonly http;
+    constructor(http: KmsHttpClient);
+    /**
+     * Liveness probe (`GET /health`, no auth). Does NOT require the KMS feature
+     * flag to be enabled.
+     */
+    health(): Promise<KmsHealthResponse>;
+    /**
+     * Version / capability descriptor (`GET /version`, no auth). Does NOT require
+     * the KMS feature flag to be enabled.
+     */
+    version(): Promise<KmsVersionResponse>;
+    /**
+     * Request-queue health and circuit-breaker state (`GET /QueueStatus`).
+     */
+    queueStatus(): Promise<KmsQueueStatusResponse>;
+    /**
+     * RPMB anti-rollback monotonic counter (`GET /RollbackCounter`, diagnostic,
+     * v0.20.0).
+     */
+    rollbackCounter(): Promise<KmsRollbackCounterResponse>;
+    /**
+     * Machine-readable runtime statistics (`GET /stats`, v0.20.0) — wallets, tx,
+     * queue, warnings.
+     */
+    stats(): Promise<KmsStatsResponse>;
+    /**
+     * TEE remote-attestation evidence bound to a caller nonce (`GET /attestation`,
+     * #37). Public (no auth) — pass a fresh random `nonce` (hex, ≤64 bytes) to bind
+     * the evidence + defeat replay, then verify the returned signed measurement.
+     */
+    getAttestation(nonce: string): Promise<KmsAttestationResponse>;
+    /**
+     * Ed25519-signed measurement manifest, version → ta_measurement
+     * (`GET /.well-known/attestation-measurements.json`, #12). Public.
+     */
+    getAttestationMeasurements(): Promise<KmsAttestationManifestResponse>;
+    /**
+     * Sigsum transparency proof sidecar for the measurement manifest
+     * (`GET /.well-known/attestation-measurements-proof.json`, #87). Public.
+     */
+    getAttestationMeasurementsProof(): Promise<KmsAttestationProofResponse>;
+    /**
+     * WARNING — DESTRUCTIVE, IRREVERSIBLE. Force-purges a key from both the TEE
+     * and the SQLite store with NO passkey/WebAuthn check (`POST /admin/purge-key`,
+     * v0.20.0). Operator-only: authorised solely by the `KMS_ADMIN_TOKEN` operator
+     * secret sent as `Authorization: Bearer <adminToken>`. There is no recovery
+     * once a key is purged.
+     *
+     * @internal Operator/break-glass tooling only — not part of the general SDK surface.
+     *   The endpoint is gated server-side and intentionally omitted from the public KMS
+     *   docs; do not expose it in application-facing flows.
+     */
+    adminPurgeKey(params: {
+        key_id: string;
+        reason: string;
+    }, adminToken: string): Promise<KmsPurgeKeyResponse>;
+}
+
+/**
+ * In-memory storage adapter — useful for testing and demos.
+ * All data is lost when the process exits.
+ */
+declare class MemoryStorage implements IStorageAdapter {
+    private accounts;
+    private transfers;
+    private paymasters;
+    private blsConfig;
+    getAccounts(): Promise<AccountRecord[]>;
+    saveAccount(account: AccountRecord): Promise<void>;
+    findAccountByUserId(userId: string): Promise<AccountRecord | null>;
+    updateAccount(userId: string, updates: Partial<AccountRecord>): Promise<void>;
+    saveTransfer(transfer: TransferRecord): Promise<void>;
+    findTransfersByUserId(userId: string): Promise<TransferRecord[]>;
+    findTransferById(id: string): Promise<TransferRecord | null>;
+    updateTransfer(id: string, updates: Partial<TransferRecord>): Promise<void>;
+    getPaymasters(userId: string): Promise<PaymasterRecord[]>;
+    savePaymaster(userId: string, paymaster: PaymasterRecord): Promise<void>;
+    removePaymaster(userId: string, name: string): Promise<boolean>;
+    getBlsConfig(): Promise<BlsConfigRecord | null>;
+    updateSignerNodesCache(nodes: unknown[]): Promise<void>;
+}
+
+/**
+ * Local wallet signer — backs all users with a single private key.
+ * Suitable for testing, demos, and single-tenant server setups.
+ *
+ * For multi-tenant production use, implement ISignerAdapter with
+ * per-user key management (e.g., KMS, HSM, or encrypted database).
+ */
+declare class LocalWalletSigner implements ISignerAdapter {
+    private readonly account;
+    constructor(privateKey: string);
+    getAddress(_userId: string): Promise<`0x${string}`>;
+    signMessage(_userId: string, message: `0x${string}` | Uint8Array, _ctx?: PasskeyAssertionContext): Promise<`0x${string}`>;
+    ensureSigner(_userId: string): Promise<{
+        address: `0x${string}`;
+    }>;
+}
+
+export { ACCOUNT_ABI, AGENT_SESSION_KEY_VALIDATOR_ABI, AIRACCOUNT_ABI, AIRACCOUNT_ADDRESSES, AIRACCOUNT_FACTORY_ABI, AIR_ACCOUNT_COMPOSITE_VALIDATOR_ABI, AIR_ACCOUNT_DELEGATE_ABI, AIR_ACCOUNT_DELEGATE_ADDRESS, ALG_ID, AccountManager, type AccountRecord, type ActiveRecovery, AgentRegistryService, type AgentReputationSummary, type AgentSessionConfig, type AgentSessionInfo, AirAccountServerClient, type AirAccountVersion, BLSSignatureData, BLSSignatureService, type BeginCeremonyResponse, type BindERC8004AgentWalletParams, type BlsConfigRecord, type BuildCredentialOptions, CALLDATA_PARSER_REGISTRY_ABI, ConsoleLogger, type CreateAgentAccountParams, type CreateP256SessionKeyRequest, type CreateP256SessionKeyResponse, DEFAULT_CREDENTIAL_ID, DEFAULT_KMS_ENDPOINT, DEFAULT_ORIGIN, DEFAULT_RP_ID, type DelegateInitParams, DvtPendingConfirmationError, type EIP7702Authorization, EIP7702DelegateService, ENTRYPOINT_ABI_V6, ENTRYPOINT_ABI_V7_V8, ENTRYPOINT_ADDRESSES, ERC20_ABI, ERC8004Service, ERC8004_ADDRESSES, EXECUTE_BATCH_SELECTOR, EXECUTE_SELECTOR, EXECUTE_USER_OP_SELECTOR, type EntryPointConfig, EntryPointVersion, type EntryPointVersionConfig, type EstimateGasParams, EthereumProvider, type ExecuteTransferParams, FACTORY_ABI_V6, FACTORY_ABI_V7_V8, FORCE_EXIT_MODULE_ABI, ForceExitService, GLOBAL_GUARD_ABI, type GrantP256SessionParams, type GrantSessionParams, GuardChecker, type GuardState, GuardStateReader, GuardStatus, type ILogger, type ISignerAdapter, type IStorageAdapter, type InstallModuleParams, KmsAgentService, type KmsAttestationManifestResponse, type KmsAttestationProofResponse, type KmsAttestationResponse, type KmsBeginAuthenticationRequest, type KmsBeginAuthenticationResponse, type KmsBeginGrantSessionAuthRequest, type KmsBeginGrantSessionAuthResponse, type KmsBeginRegistrationRequest, type KmsBeginRegistrationResponse, type KmsChangePasskeyResponse, type KmsCompleteRegistrationRequest, type KmsCompleteRegistrationResponse, type KmsCreateAgentKeyRequest, type KmsCreateAgentKeyResponse, type KmsCreateKeyRequest, type KmsCreateKeyResponse, type KmsDeleteKeyResponse, type KmsDeriveAddressResponse, type KmsDescribeKeyResponse, type KmsEip712Domain, type KmsEip712FieldValue, type KmsEip712TypeDef, type KmsEthereumTransaction, type KmsGetPublicKeyResponse, type KmsHealthResponse, KmsHttpClient, type KmsHttpClientOptions, type KmsKeyStatusResponse, type KmsListKeysResponse, KmsManager, KmsMonitorService, type KmsPaymentAuth, type KmsPaymentSignatureResponse, KmsPaymentSigner, type KmsPurgeKeyResponse, type KmsQueueStatusResponse, type KmsRefreshAgentCredentialRequest, type KmsRefreshAgentCredentialResponse, type KmsRevokeAgentCredentialRequest, type KmsRevokeAgentCredentialResponse, type KmsRollbackCounterResponse, KmsSessionService, type KmsSignAgentRequest, type KmsSignAgentResponse, type KmsSignGTokenAuthorizationRequest, type KmsSignGrantSessionRequest, type KmsSignGrantSessionResponse, type KmsSignHashResponse, type KmsSignMicropaymentVoucherRequest, type KmsSignP256GrantSessionRequest, type KmsSignRequest, type KmsSignResponse, type KmsSignTypedDataRequest, type KmsSignTypedDataResponse, type KmsSignX402PaymentRequest, KmsSigner, type KmsStatsResponse, type KmsVersionResponse, type L2Type, L2_TYPE, type LegacyPasskeyAssertion, LocalWalletSigner, MAX_GUARDIANS, MODULE_TYPE, MemoryStorage, type MintAgentIdentityParams, ModuleManager, type ModuleTypeId, type OapdConfig, P256PasskeySigner, PackedUserOperation, type PasskeyAssertionContext, type PasskeyCeremonySigner, PaymasterManager, PaymasterPriceStalenessError, type PaymasterRecord, type PendingExit, type PendingWeightChange, PreCheckResult, type QueryAgentReputationParams, RECOVERY_THRESHOLD, RECOVERY_TIMELOCK_SECONDS, RecoveryService, type RevokeP256SessionKeyRequest, type RevokeP256SessionKeyResponse, type RunCeremonyOptions, SESSION_KEY_VALIDATOR_ABI, type ServerConfig, type SessionInfo, SessionKeyService, type SetAgentWalletParams, type SignP256UserOpRequest, type SignP256UserOpResponse, SilentLogger, type SubmitAgentReputationParams, TIER_GUARD_HOOK_ABI, TierConfig, TierLevel$1 as TierLevel, type TokenBalance, type TokenGuardState, type TokenInfo, TokenService, TransferManager, type TransferRecord, type TransferResult, type UninstallModuleParams, UserOperation, VALIDATOR_ABI, WEIGHT_CHANGE_EXPIRY_SECONDS, WEIGHT_CHANGE_THRESHOLD, WEIGHT_CHANGE_TIMELOCK_SECONDS, WalletManager, type WebAuthnAssertion, type WebAuthnAuthenticationCredential, type WeightConfig, WeightedSignatureService, YAAAServerClient, base64UrlDecode, base64UrlEncode, beginAuthenticationChallenge, beginGrantSessionChallenge, buildAuthenticationCredential, buildAuthenticatorData, buildClientDataJSON, buildInstallModuleHash, buildUninstallModuleHash, computeOapdSalt, erc8004AddressesForChain, getOapdAddress, getOapdAddressWithChainId, isExecuteUserOpWrapped, isOapdDeployed, isPendingConfirmation, packP256SessionSignature, packSecp256k1SessionSignature, runAuthenticationCeremony, runGrantSessionCeremony, runWebAuthnCeremony, sepoliaV07Config, validateConfig, wrapExecuteUserOp };