@terminal3/t3n-sdk 4.9.0 → 4.10.1

package/dist/index.d.ts

@@ -383,1408 +383,1235 @@ declare function createEmailOtpAuthInput(credentials: EmailOtpCredentials): Emai
 declare function createWorkloadAuthInput(provider: string, idToken: string): WorkloadAuthInput;
 
 /**
- * Error classes for T3n SDK
- */
-/**
- * Base error class for T3n SDK errors
+ * Public types export for T3n SDK
  */
-declare class T3nError extends Error {
-    readonly code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
-}
 /**
- * Error thrown when session is in invalid state for operation
+ * Guest-to-Host request handler function type
+ *
+ * Handles requests from WASM guest that need host (SDK) to perform side
+ * effects. The exact shape of `requestData` depends on the specific
+ * handler — see `GuestToHostHandlers` below for the per-handler shapes.
+ * The wrapper layer in `T3nClient.handleGuestToHost` parses the JSON
+ * envelope and calls the matching handler with the parsed data, so
+ * each handler's implementation should narrow `requestData` to its
+ * own expected shape.
  */
-declare class SessionStateError extends T3nError {
-    readonly currentState: string;
-    constructor(message: string, currentState: string);
-}
+type GuestToHostHandler = (requestData: Record<string, unknown>) => Promise<Uint8Array>;
 /**
- * Error thrown during authentication process
+ * Map of guest-to-host request handlers
+ * Keys match the guest_to_host tag values from the WASM
  */
-declare class AuthenticationError extends T3nError {
-    readonly authMethod?: string | undefined;
-    constructor(message: string, authMethod?: string | undefined);
+interface GuestToHostHandlers {
+    /**
+     * Handle Ethereum signature requests
+     * requestData: { guest_to_host: "EthSign", challenge: string (base64) }
+     * Returns: JSON bytes of { host_to_guest: "EthSign", challenge: string, signature: string }
+     */
+    EthSign?: GuestToHostHandler;
+    /**
+     * Handle MlKem public key requests
+     * requestData: { guest_to_host: "MlKemPublicKey" }
+     * Returns: JSON bytes of { host_to_guest: "MlKemPublicKey", key: string }
+     */
+    MlKemPublicKey?: GuestToHostHandler;
+    /**
+     * Handle random bytes requests
+     * requestData: { guest_to_host: "Random", len?: number }
+     * Returns: JSON bytes of { host_to_guest: "Random", bytes: string (base64) }
+     */
+    Random?: GuestToHostHandler;
+    [key: string]: GuestToHostHandler | undefined;
 }
+
 /**
- * Error thrown during handshake process
+ * Transport layer for T3n SDK
+ *
+ * Abstracts the communication with T3n nodes, allowing for different
+ * implementations (HTTP, WebSocket, Mock) and easy testing.
  */
-declare class HandshakeError extends T3nError {
-    constructor(message: string);
-}
 /**
- * Error thrown when a session-authenticated SDK client detects that the
- * caller-owned session is no longer usable and the caller must
- * re-authenticate before the call can succeed.
- *
- * Unlike {@link OrgDataClient} (which owns its ETH-secret-driven session
- * and silently rebuilds it on expiry), {@link SessionOrgDataClient} is
- * handed a caller-owned `T3nClient` whose session is bound to an
- * interactive flow (typically SIWE). The SDK can't re-authenticate
- * non-interactively, so on the same wire patterns that the
- * self-owned client recovers from, the session-bound client translates
- * the underlying error into this class and rethrows. The original error
- * is preserved on the native ES2022 `cause` property.
- *
- * Callers branch on `instanceof SessionExpiredError` to route the user
- * to a re-auth UX (e.g. SIWE modal / login redirect) rather than
- * parsing the message of a raw {@link RpcError}.
+ * JSON-RPC request structure
  */
-declare class SessionExpiredError extends T3nError {
-    constructor(cause: unknown);
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params: unknown;
+    id: string | number;
 }
 /**
- * Error thrown during RPC communication.
- *
- * `message` is the human-readable error (preferring the server's
- * `error.data.detail` when present, with the request id appended in
- * `[<id>]` form so a UI that only surfaces `.message` still gives an
- * operator something to grep). The structured fields below preserve
- * the same info for callers that want to render or log them
- * separately — e.g. a toast that shows `detail` but surfaces
- * `requestId` in a "copy for support" affordance.
+ * JSON-RPC response structure
  */
-declare class RpcError extends T3nError {
-    readonly rpcMethod?: string | undefined;
-    readonly httpStatus?: number | undefined;
-    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
-     *  carry the specific reason here; internal kinds omit it. */
-    readonly detail?: string | undefined;
-    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
-    readonly requestId?: string | undefined;
-    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined, 
-    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
-     *  carry the specific reason here; internal kinds omit it. */
-    detail?: string | undefined, 
-    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
-    requestId?: string | undefined);
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id: string | number;
 }
 /**
- * Error thrown when an OTP send is throttled by the node.
- *
- * The email-OTP login flow's `InitEmailOtp` step refuses a send when a
- * still-valid code was issued within the resend cooldown
- * (`reason: "cooldown_active"`) or the rolling per-recipient send cap is
- * exhausted (`reason: "send_cap_exceeded"`). Previously a cooldown-
- * suppressed resend returned a silent success, leaving a user who never
- * received the first code at a dead end; this typed error lets the app
- * render a "you just requested a code — retry in {retryAfterSecs}s"
- * affordance instead.
- *
- * Recognised from the node's stable
- * `OtpRateLimited (reason=…, retry_after_secs=…)` wire token (pinned by a
- * server-side test). Subclass of {@link RpcError} so callers that catch
- * the parent still see `httpStatus`/`requestId`; callers that want the
- * typed surface `instanceof OtpRateLimitedError` to read `reason` and
- * `retryAfterSecs`.
- *
- * Retryable after `retryAfterSecs` (caller-side back-off).
+ * Transport interface for sending requests to T3n nodes
  */
-declare class OtpRateLimitedError extends RpcError {
-    /** Stable reason code: `"cooldown_active"` or `"send_cap_exceeded"`. */
-    readonly reason: string;
-    /** Seconds to wait before retrying the send (parsed from `retry_after_secs=`). */
-    readonly retryAfterSecs: number;
-    constructor(message: string, 
-    /** Stable reason code: `"cooldown_active"` or `"send_cap_exceeded"`. */
-    reason: string, 
-    /** Seconds to wait before retrying the send (parsed from `retry_after_secs=`). */
-    retryAfterSecs: number, rpcMethod?: string, requestId?: string);
+interface Transport {
+    /**
+     * Send a JSON-RPC request to the T3n node
+     * @param request - The JSON-RPC request to send
+     * @param headers - Additional headers to include
+     * @returns Promise that resolves to the JSON-RPC response
+     */
+    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
+    /**
+     * Send a JSON-RPC request with an attached binary blob (multipart/form-data).
+     * Part 1 (name=jsonrpc): JSON-RPC envelope.
+     * Part 2 (name=blob): raw binary bytes (e.g. WASM bytecode).
+     */
+    sendMultipart?(request: JsonRpcRequest, headers: Record<string, string>, blob: Blob): Promise<JsonRpcResponse>;
+    /**
+     * Optional accessor for the latest Set-Cookie header value.
+     * (Useful in Node.js demos/tests; browsers block HttpOnly cookies.)
+     */
+    getLastSetCookie?(): string | null;
+    /**
+     * Optional accessor for the last response headers (debugging).
+     */
+    getLastResponseHeaders?(): Record<string, string>;
 }
 /**
- * Error thrown when WASM operations fail
+ * HTTP transport implementation using fetch
  */
-declare class WasmError extends T3nError {
-    readonly operation?: string | undefined;
-    readonly payload?: unknown | undefined;
-    constructor(message: string, operation?: string | undefined, payload?: unknown | undefined);
+declare class HttpTransport implements Transport {
+    private baseUrl;
+    private timeout;
+    private lastSetCookie;
+    private lastResponseHeaders;
+    /**
+     * Cookie jar (`name -> value`) for non-browser callers. The session is
+     * node-local in-memory state, so once the load balancer pins a client
+     * to a node via its `GCLB` session-affinity cookie, every later request
+     * in the session must carry that cookie back or it gets re-balanced to
+     * a node that has never seen the handshake → `401 session not found`.
+     * Browsers replay the cookie automatically from their own jar (via
+     * `credentials: "include"`); plain `fetch` callers (Node demos, tests,
+     * server-side SDK usage) have no jar, so we keep one here. Empty in
+     * browsers — there `getSetCookie()` is unavailable and a script-set
+     * `Cookie` header is forbidden, so this stays inert.
+     */
+    private cookieJar;
+    constructor(baseUrl: string, timeout?: number);
+    getLastSetCookie(): string | null;
+    getLastResponseHeaders(): Record<string, string>;
+    /**
+     * Record response headers and merge any `Set-Cookie` into the jar.
+     *
+     * undici's `Headers` exposes `getSetCookie()` (one entry per cookie);
+     * the DOM `Headers` type doesn't declare it, so cast structurally. In
+     * browsers neither `getSetCookie()` nor reading `set-cookie` is
+     * permitted, so `setCookies` is empty and the jar is left untouched.
+     */
+    private captureResponseMetadata;
+    /**
+     * Build a `Cookie` request header from the jar so non-browser callers
+     * stay pinned to the node holding their session. Returns `{}` when the
+     * jar is empty — always the case in browsers, leaving their native
+     * cookie handling untouched.
+     *
+     * `callerHeaders` is checked case-insensitively: if the caller already
+     * supplied a `Cookie`/`cookie` header, the jar yields to it entirely.
+     * (Object spread keys are case-sensitive, but `fetch`'s `Headers` are
+     * not — emitting `Cookie` here while the caller passed `cookie` would
+     * make the two coexist and get comma-combined instead of overridden.)
+     */
+    private cookieHeader;
+    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
+    sendMultipart(request: JsonRpcRequest, headers: Record<string, string>, blob: Blob): Promise<JsonRpcResponse>;
 }
 /**
- * Decode WASM error message from comma-separated byte array format
- * WASM errors often come as "83,101,114,100,101..." which represents ASCII bytes
+ * Mock transport for testing
  *
- * @param errorMessage - The error message string that may contain comma-separated bytes
- * @returns Decoded error message if it was encoded, otherwise original message
- */
-declare function decodeWasmErrorMessage(errorMessage: string): string;
-/**
- * Extract and decode error from WASM ComponentError
+ * @example
+ * ```typescript
+ * const mockTransport = new MockTransport();
+ * mockTransport.mockResponse("auth.handshake", { result: "..." });
  *
- * @param error - The error object from WASM
- * @returns Decoded error message
- */
-declare function extractWasmError(error: unknown): string;
-
-/**
- * Wire types for the explicit `otp-request` /
- * `otp-verify` / slim `user-upsert` exports on `tee:user/contracts`
- * (`tee:user@2.0.0`).
- *
- * Pre-2.0.0 the user contract dispatched OTP request and OTP verify
- * implicitly from the input shape of a single `user-upsert` call.
- * 2.0.0 splits that surface into three explicit functions; the
- * shapes here mirror the OTP / user-upsert wire contract.
- *
- * Bytes flow directly from the contract
- * through the JSON-RPC envelope into the SDK wrappers
- * (`T3nClient.otpRequest`, `T3nClient.otpVerify`,
- * `T3nClient.submitUserInput`).
+ * const client = new T3nClient({
+ *   trustAnchor: { unsafe_trust_server: true },
+ *   transport: mockTransport,
+ *   wasmComponent: mockWasm,
+ * });
+ * ```
  */
+declare class MockTransport implements Transport {
+    private responses;
+    private responseHeaders;
+    private lastResponseHeaders;
+    private requests;
+    private multipartRequests;
+    /**
+     * Mock a response for a specific method
+     */
+    mockResponse(method: string, response: Partial<JsonRpcResponse>): void;
+    /**
+     * Mock response headers for a specific method. Used by tests to
+     * simulate the server-minted `Session-Id` header the SDK picks up
+     * from the `auth.handshake` response. Unset methods
+     * default to no headers.
+     */
+    mockResponseHeaders(method: string, headers: Record<string, string>): void;
+    /**
+     * Mock an error response for a specific method
+     */
+    mockError(method: string, code: number, message: string, data?: unknown): void;
+    getLastResponseHeaders(): Record<string, string>;
+    /**
+     * Get all requests that were sent
+     */
+    getRequests(): Array<{
+        request: JsonRpcRequest;
+        headers: Record<string, string>;
+    }>;
+    /**
+     * Get requests for a specific method
+     */
+    getRequestsForMethod(method: string): Array<{
+        request: JsonRpcRequest;
+        headers: Record<string, string>;
+    }>;
+    getMultipartRequests(): Array<{
+        request: JsonRpcRequest;
+        headers: Record<string, string>;
+        blob: Blob;
+    }>;
+    /**
+     * Clear all recorded requests
+     */
+    clearRequests(): void;
+    sendMultipart(request: JsonRpcRequest, headers: Record<string, string>, blob: Blob): Promise<JsonRpcResponse>;
+    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
+}
 
 /**
- * OTP delivery channel. Matches the `OtpContactChannel` Rust enum
- * with `serde(rename_all = "snake_case")`.
- */
-type OtpChannel = "email" | "sms";
-/**
- * Discriminated OTP contact target. Mirrors the Rust `OtpRequest` enum
- * (`email_channel` / `sms_channel` on the wire). Exactly one branch is
- * set — no parallel optional email + phone with a separate channel tag.
- *
- * The legacy `keys.generic_api.otp_channel` body shadow was removed
- * in 2.0.0 — the contract rejects calls carrying it with a
- * `legacy_field` error.
- */
-type OtpRequestInput = {
-    emailChannel: {
-        emailAddress: string;
-    };
-} | {
-    smsChannel: {
-        phoneNumber: string;
-    };
-};
-/**
- * Response returned by `otp-request`. Mirrors the OTP wire response.
+ * TDX quote verifier backed by the Rust `signature` crate compiled to
+ * WASM. Full cryptographic verification: ECDSA P-256 attestation-key
+ * signature, PCK certificate chain walk to Intel's root CA, and
+ * report_data + RTMR comparison.
  *
- * - `contact` echoes the OTP destination so clients that race
- *   multiple channels can correlate replies.
- * - `expiresAtSec` is the Unix-second TTL the host minted for the
- *   pending OTP. Absent in `skip_otp` test environments.
- * - `status` is `"otp_pending"` on the happy path. `"otp_failed"`
- *   only appears on retry without a fresh request — usually you
- *   shouldn't see it on `otp-request`.
- * - `txHash` is the host-enriched ledger ref for the OTP-pending
- *   write (the contract leaves it `null`; the host injects).
- * - `isNewProfile` is `true` on a fresh DID's first OTP request —
- *   read this to detect "did the user just register".
- */
-interface OtpRequestResult {
-    contact: string;
-    channel: OtpChannel;
-    expiresAtSec?: number;
-    status?: string;
-    txHash?: string;
-    isNewProfile?: boolean;
-}
-/**
- * Input to `T3nClient.otpVerify`. `otpCode` is mandatory; `request`
- * repeats the same discriminated contact shape as {@link OtpRequestInput}.
+ * The WASM bytes are inlined as base64 (see quote_verifier_bytes.ts)
+ * so the SDK works without bundler WASM plugins and without runtime
+ * asset URL resolution.
  */
-interface OtpVerifyInput {
-    otpCode: string;
-    request: OtpRequestInput;
+interface QuoteVerifyResult {
+    valid: boolean;
+    error?: string;
+    rtmr3?: string;
+    report_data?: string;
 }
-/**
- * Suggestion surfaced when the bind-target contact already belongs
- * to another DID. The contract refuses to silently steal the
- * authenticator; the caller must resolve the merge (typically via
- * `merge-profiles`) before re-attempting verify.
- */
-interface OtpMergeSuggestion {
-    existingDid: string;
-    currentDid: string;
-    email?: string;
-    phone?: string;
-    channel: OtpChannel;
+interface PeerQuoteResult {
+    peer_id: string;
+    valid: boolean;
+    error?: string;
+    rtmr3?: string;
 }
-/**
- * Response returned by `otp-verify`. Mirrors the OTP-verify wire response.
- *
- * - `email` is populated on `channel = "email"` success;
- *   `phone` on `channel = "sms"` success. Mutually exclusive on
- *   the happy path.
- * - `status` carries `"otp_failed"` / `"otp_expired"` on retry; the
- *   happy path leaves it `undefined`.
- * - `mergeSuggestion` is set when the contact-to-bind is already
- *   owned by another DID. Wire it into your merge UX.
- */
-interface OtpVerifyResult {
-    txHash?: string;
-    did: string;
-    channel: OtpChannel;
-    email?: string;
-    phone?: string;
-    status?: string;
-    mergeSuggestion?: OtpMergeSuggestion;
-    isNewProfile?: boolean;
+interface DkgVerifyResult {
+    valid: boolean;
+    results: PeerQuoteResult[];
+    valid_count: number;
+    expected_count: number;
+    error?: string;
 }
 /**
- * Level-1 user-input fields accepted by the slim `user-upsert`. Field names
- * are the on-the-wire names — `submitUserInput` sends this object verbatim,
- * so keys must match the contract exactly (snake_case). The canonical Level-1
- * set is the six fields below; the shape is intentionally open so callers can
- * add provider-specific fields the contract knows how to merge.
+ * Client-pinned anchor the DKG attestation bundle is verified against.
  *
- * `email_address` / `phone_number` are normally bound via the OTP roundtrip
- * before `submitUserInput`, but the contract accepts them directly here too.
- */
-interface UserInputProfile {
-    first_name?: string;
-    last_name?: string;
-    country_of_residence?: string;
-    document_issuance_country?: string;
-    ssn?: string;
-    address?: string;
-    email_address?: string;
-    phone_number?: string;
-    campaign_code?: string;
-    role?: string;
-    [key: string]: unknown;
-}
-/**
- * Input to `T3nClient.submitUserInput`. Maps onto the slim
- * `user-upsert` request shape: `{ profile, organisation_did?,
- * attestations?, keys? }`.
+ * Without it, "the server proved it runs in a TEE" only means "*some*
+ * TDX box somewhere" — any attacker with their own TDX cloud VM can
+ * forge a complete, cryptographically-valid bundle for their own key
+ * (SP-003). The anchor is the independent ground truth that closes it:
+ * the bundle must describe *our* cluster (`expected_peer_ids`) running
+ * *our* image (`rtmr3_allowlist`).
  */
-interface SubmitUserInputArgs {
-    profile: UserInputProfile;
-    organisationDid?: string;
-    attestations?: unknown;
-    keys?: Record<string, unknown>;
+interface TrustAnchor {
     /**
-     * KYC webhook orphan-attestation flow. When set, the contract
-     * skips the email-not-verified gate and only records the
-     * attestation if the DID has no profile yet.
-     * Most callers should leave this `undefined`.
+     * Base58 peer IDs the client expects in the cluster. The bundle's
+     * `peer_ids` must equal this set exactly (order-insensitive) — a MITM
+     * cannot substitute its own single-node participant set.
      */
-    requireExistingUser?: boolean;
+    expected_peer_ids: string[];
     /**
-     * Testnet self-admit. When `true`, the contract additionally
-     * runs the self-admit side-effect after the profile commit: writes
-     * the caller's DID into `idx:_tenants` + `idx:_tenant_quotas` and
-     * mints any operator-configured welcome credits. Inspect the
-     * `tenantAdmit` field on the response for the outcome.
-     *
-     * Testnet-only. Production clusters return
-     * `tenantAdmit.status = "refused"` with
-     * `reason = "not_testnet" | "self_admit_disabled" | "not_eth_derived"`.
-     * The profile commit always succeeds regardless of the inner outcome.
-     *
-     * Most callers should leave this `undefined`.
+     * Base64-encoded 48-byte RTMR3 measurements of the expected node
+     * image. Every quote's RTMR3 must be a member. **Must be non-empty.**
+     * An array (not a singleton) so a rolling deploy's two in-flight
+     * image measurements both verify.
      */
-    becomeDevTenant?: boolean;
+    rtmr3_allowlist: string[];
 }
 /**
- * Testnet self-admit projection from `user-upsert`. Present only
- * when the caller set `becomeDevTenant: true` on the request.
+ * Escape hatch for local dev / tests against a node whose attestation
+ * can't be anchored (e.g. a mock signer that publishes no bundle).
  *
- * - `status: "admitted"` — first call for this DID; tenant record
- *   committed and (if configured) welcome credits minted into
- *   `grantedCredits`.
- * - `status: "already-admitted"` — replay; idempotent no-op.
- * - `status: "refused"` — the cluster declined the self-admit;
- *   `reason` is the machine-readable cause (`not_testnet`,
- *   `self_admit_disabled`, `not_eth_derived`), `detail` is a
- *   human-readable string.
- */
-type TenantAdmitStatus = "admitted" | "already-admitted" | "refused";
-interface TenantAdmitProjection {
-    status: TenantAdmitStatus;
-    grantedCredits?: string;
-    reason?: string;
-    detail?: string;
-}
-/**
- * Response shape returned by the slim `user-upsert`. Carries the
- * post-merge tx hash plus the Level-1 merge diagnostics
- * (`refusedFields`, `mergeSuggestion`) the pre-2.0.0 omnibus
- * `UpsertResponse` already surfaced.
+ * The name is deliberately alarming so it stands out in code review and
+ * grep — it is the *only* way to skip DKG attestation verification on
+ * the handshake path.
  */
-interface SubmitUserInputResult {
-    txHash?: string;
-    refusedFields?: string[];
-    mergeSuggestion?: OtpMergeSuggestion;
-    userFound?: boolean;
-    /**
-     * Testnet self-admit projection. Present only when the caller
-     * set `becomeDevTenant: true` on the request.
-     */
-    tenantAdmit?: TenantAdmitProjection;
+interface UnsafeTrustServer {
+    unsafe_trust_server: true;
 }
+type TrustAnchorOrUnsafe = TrustAnchor | UnsafeTrustServer;
+/** Narrow a {@link TrustAnchorOrUnsafe} to the explicit opt-out arm. */
+declare function isUnsafeTrustServer(anchor: TrustAnchorOrUnsafe): anchor is UnsafeTrustServer;
 /**
- * Discriminator for {@link UserUpsertError}. Mirrors the
- * `UserUpsertError` wire enum and its `<code>:<detail>` wire
- * format. Branch with a `switch` over `kind`.
+ * Verify a single TDX attestation quote with full cryptographic verification.
  *
- * - `EmailNotVerified` — the slim `user-upsert` was called against
- *   a DID that has no verified email and no proving authenticator.
- *   Run `otpRequest` + `otpVerify` first (or accept an
- *   OIDC/Email-authed session).
- * - `LegacyField` — caller passed a pre-2.0.0 dispatch field
- *   (`otp_code` to a non-verify export, or
- *   `keys.generic_api.otp_channel` anywhere). Migrate the call
- *   site to the new explicit functions.
- * - `UserNotFound` — `requireExistingUser` was set but no profile
- *   exists for the DID. The attestation is recorded for audit;
- *   no profile created.
+ * @param quoteB64 - Base64-encoded raw TDX v4 quote
+ * @param attestationMsgB64 - Base64-encoded attestation message
+ *   (for DKG: encaps_key || sorted_peer_id_bytes)
+ * @param expectedRtmr3B64 - Optional base64-encoded 48-byte RTMR3
+ * @returns Verification result with extracted measurements
  */
-type UserUpsertErrorKind = "EmailNotVerified" | "LegacyField" | "UserNotFound";
+declare function verifyTdxQuote(quoteB64: string, attestationMsgB64: string, expectedRtmr3B64?: string): Promise<QuoteVerifyResult>;
 /**
- * Typed wrapper for the `<code>:<detail>` errors the slim
- * `user-upsert` and the OTP entry points emit. `kind` is the
- * structured discriminator the SDK derives from the error code
- * prefix; `code` and `detail` retain the wire components for
- * fall-through logging.
+ * Verify a full DKG attestation bundle against a client-pinned
+ * {@link TrustAnchor}: multiple TDX quotes from all participating
+ * nodes, plus the binding between the quotes and the ML-KEM
+ * encapsulation key. Checks:
+ *   1. `expected_peer_ids` / `rtmr3_allowlist` are both non-empty
+ *   2. the bundle's `peer_ids` equal the pinned set exactly
+ *   3. attestationMsg starts with encapsKey (server can't swap the key)
+ *   4. every quote's ECDSA signature chains to Intel's SGX root CA
+ *   5. every quote's report_data == keccak512(attestationMsg)
+ *   6. every quote's RTMR3 is a member of `rtmr3_allowlist`
  *
- * Throw site: `T3nClient.submitUserInput` (and friends) when the
- * contract returns a string error matching the
- * `<code>:<detail>` shape.
+ * The anchor is **required**: there is no unauthenticated mode. Callers
+ * that genuinely want to trust the server must not call this at all —
+ * see `unsafe_trust_server` on the client config, which branches around
+ * the whole verify path.
+ *
+ * @param encapsKeyB64 - Base64-encoded ML-KEM encapsulation key
+ *   (from `/status.encaps_key`)
+ * @param attestationMsgB64 - Base64-encoded raw attestation message
+ *   (from `/status.dkg_attestation.attestation_msg`)
+ * @param peerIds - Base58 peer IDs as reported by the bundle
+ * @param quotes - Map of peer_id → base64-encoded TDX quote
+ * @param anchor - Client-pinned expected peer IDs + RTMR3 allowlist
+ * @returns Per-peer verification results and overall validity
  */
-declare class UserUpsertError extends T3nError {
-    readonly kind: UserUpsertErrorKind | "Unknown";
-    readonly detail: string;
-    constructor(code: string, detail: string);
-    /**
-     * Try to parse a contract error string into a `UserUpsertError`.
-     * Returns `null` if `raw` doesn't match the `<code>:<detail>`
-     * shape — caller falls back to a generic error.
-     */
-    static fromWire(raw: string): UserUpsertError | null;
-}
+declare function verifyDkgAttestation(encapsKeyB64: string, attestationMsgB64: string, peerIds: string[], quotes: Record<string, string>, anchor: TrustAnchor): Promise<DkgVerifyResult>;
 
 /**
- * Org-data wire types mirroring the org-data contract wire shapes.
- *
- * Plain TypeScript interfaces (no zod) — the SDK does not use a
- * validation library for domain types; see the existing `types/` files.
- *
- * Each response type below is paired with a shallow runtime predicate
- * (`isMutationResponse`, `isOrgPolicyMeta`, etc.) so the org-data client
- * can `assertShape` the decoded payload before returning to callers.
- * Predicates check the top-level structure only; nested elements
- * (e.g. each `UserGrant` inside `OrgContractGrants.grants`) are not
- * deeply validated — see `utils/shape.ts` for the rationale.
- *
- * Reference: the org-data wire contract.
+ * Configuration types for T3n Client
  */
+
 /**
- * Capability grant stored under `ORG_CONTRACT_GRANTS_MAP`.
- *
- * Mirrors the org-data `UserGrant` wire shape.
+ * Configuration interface for T3n Client
  */
-interface UserGrant {
-    /** The user this grant applies to (`did:t3n:<40-hex>`). */
-    user_did: string;
-    /** WIT function names the user may invoke (e.g. `"set-records"`). */
-    functions: string[];
-    /** Data scope paths the user may access (e.g. `"example/records"`). */
-    scopes: string[];
+interface T3nClientConfig {
+    /** Base URL of the T3n node (used if transport not provided) */
+    baseUrl?: string;
+    /** WASM component instance for cryptographic operations */
+    wasmComponent: WasmComponent;
+    /** Optional transport layer - if not provided, uses HttpTransport with baseUrl */
+    transport?: Transport;
+    /** Optional request timeout in milliseconds (default: 30000) - used for HttpTransport */
+    timeout?: number;
+    /** Optional custom headers to include in requests */
+    headers?: Record<string, string>;
     /**
-     * Optional key-value constraints that must match the request metadata
-     * exactly for every key present in this map.
+     * Log level for this client instance.
+     * Defaults to global log level (LogLevel.ERROR) if not specified.
+     * Use LogLevel.DEBUG for verbose logging, LogLevel.INFO for informational messages,
+     * LogLevel.WARN for warnings, or LogLevel.ERROR for errors only.
      */
-    constraints: Record<string, string>;
-    /** Unix timestamp (secs) after which this grant is expired. `null` means never expires. */
-    expires_at_secs: number | null;
-}
-/**
- * Policy record for an organisation's data tier.
- *
- * Mirrors the org-data policy-meta wire shape.
- */
-interface OrgPolicyMeta {
-    /** DIDs (`did:t3n:<40-hex>`) of users authorised to manage policy and read data. */
-    admins: string[];
-    /** Maximum number of admins allowed for this org. */
-    max_admins: number;
-    /** Unix timestamp (secs) when the policy was first created. */
-    created_at_secs: number;
-    /** Unix timestamp (secs) of the most recent policy update. */
-    updated_at_secs: number;
+    logLevel?: LogLevel;
+    /** Optional custom logger - if provided, overrides logLevel */
+    logger?: Logger;
+    /** Optional guest-to-host request handlers - provides custom behavior for WASM requests */
+    handlers?: GuestToHostHandlers;
     /**
-     * Per-org ceiling on delegation-credential validity (seconds).
+     * **Required.** Client-pinned trust anchor the node's DKG attestation
+     * is verified against before the handshake trusts its ML-KEM key
+     * (SP-003). Either a {@link TrustAnchor} (`expected_peer_ids` +
+     * `rtmr3_allowlist`) or the explicit `{ unsafe_trust_server: true }`
+     * opt-out for local dev / mock-signer nodes.
      *
-     * Absent when no org-level cap is set — the contract omits the field
-     * (never serialises null) and the cluster-wide
-     * `delegation.max_credential_validity_secs` governs instead. When set,
-     * the effective cap is `min(max_credential_validity_secs, cluster_ceiling)`.
+     * Without this, a network attacker with their own TDX VM can hand the
+     * SDK a forged-but-valid attestation for a key it controls and read
+     * every session. It is a required field precisely so no caller can
+     * omit it by accident — bypassing verification must be a visible,
+     * grep-able choice.
      */
-    max_credential_validity_secs?: number;
+    trustAnchor: TrustAnchorOrUnsafe;
 }
-/** Shallow runtime guard for {@link OrgPolicyMeta}. */
-declare function isOrgPolicyMeta(value: unknown): value is OrgPolicyMeta;
+
 /**
- * Effective org policy view returned by `org-policy-view`.
- *
- * Readable by any authenticated session (non-sensitive metadata).
- * Returns the **effective** credential validity cap:
- * `min(org.max_credential_validity_secs, cluster_ceiling)`, equal to the
- * cluster ceiling when the org has not set a per-org cap. The contract
- * always returns a value (or errors) — the field is never null.
+ * Error classes for T3n SDK
  */
-interface OrgPolicyView {
-    /**
-     * Effective delegation-credential validity cap in seconds:
-     * `min(org value, cluster ceiling)`, equal to the cluster ceiling when the
-     * org has not set a per-org cap. Always present — mirrors the contract's
-     * `PolicyViewResponse.effective_validity_secs` (org-data `org-policy-view`).
-     */
-    effective_validity_secs: number;
-}
-/** Shallow runtime guard for {@link OrgPolicyView}. */
-declare function isOrgPolicyView(value: unknown): value is OrgPolicyView;
 /**
- * Standard response returned by all policy write and data mutation operations.
- *
- * Mirrors the org-data `MutationResponse` wire shape.
+ * Base error class for T3n SDK errors
  */
-interface MutationResponse {
-    /** `"created"`, `"updated"`, or `"deleted"`. */
-    status: string;
-    /** Hex-encoded entry ID; present on data write/delete operations. */
-    entry_id?: string;
-    /** Whether the target key existed before deletion; present on single-entry deletes. */
-    deleted?: boolean;
-    /** Number of entries removed; present on `org-data-delete-scope`. */
-    deleted_entries?: number;
-    tx_hash: string | null;
+declare class T3nError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
 }
 /**
- * Shallow runtime guard for {@link MutationResponse}.
- *
- * Only the always-present fields are checked — `status` is mandatory on
- * every mutation; `tx_hash` is non-optional but nullable. The optional
- * fields (`entry_id`, `deleted`, `deleted_entries`) are not validated
- * because their presence depends on which mutation ran.
+ * Error thrown when session is in invalid state for operation
  */
-declare function isMutationResponse(value: unknown): value is MutationResponse;
+declare class SessionStateError extends T3nError {
+    readonly currentState: string;
+    constructor(message: string, currentState: string);
+}
 /**
- * Response type alias for org-writers-get.
- *
- * The wire body is `{ writers: string[] }` where each entry is
- * `did:t3n:<40-hex>`.
+ * Error thrown during authentication process
  */
-interface OrgWriters {
-    writers: string[];
+declare class AuthenticationError extends T3nError {
+    readonly authMethod?: string | undefined;
+    constructor(message: string, authMethod?: string | undefined);
 }
-/** Shallow runtime guard for {@link OrgWriters}. */
-declare function isOrgWriters(value: unknown): value is OrgWriters;
 /**
- * Response type alias for org-grants-get.
- *
- * The wire body echoes the `contract_id` alongside the grant list.
+ * Error thrown during handshake process
  */
-interface OrgContractGrants {
-    contract_id: string;
-    grants: UserGrant[];
+declare class HandshakeError extends T3nError {
+    constructor(message: string);
 }
 /**
- * Shallow runtime guard for {@link OrgContractGrants}.
+ * Error thrown when a session-authenticated SDK client detects that the
+ * caller-owned session is no longer usable and the caller must
+ * re-authenticate before the call can succeed.
  *
- * Validates the immediate envelope (`contract_id: string`, `grants:
- * array`) without recursing into each `UserGrant`. The Rust contract
- * is the source of truth for grant element shape; widening the predicate
- * here would create maintenance churn against benign field additions.
+ * Unlike {@link OrgDataClient} (which owns its ETH-secret-driven session
+ * and silently rebuilds it on expiry), {@link SessionOrgDataClient} is
+ * handed a caller-owned `T3nClient` whose session is bound to an
+ * interactive flow (typically SIWE). The SDK can't re-authenticate
+ * non-interactively, so on the same wire patterns that the
+ * self-owned client recovers from, the session-bound client translates
+ * the underlying error into this class and rethrows. The original error
+ * is preserved on the native ES2022 `cause` property.
+ *
+ * Callers branch on `instanceof SessionExpiredError` to route the user
+ * to a re-auth UX (e.g. SIWE modal / login redirect) rather than
+ * parsing the message of a raw {@link RpcError}.
  */
-declare function isOrgContractGrants(value: unknown): value is OrgContractGrants;
-/** Response for `org-data-list`. */
-interface DataListResponse {
-    /** Hex-encoded entry IDs for this page. */
-    entry_ids: string[];
-    /** Offset to pass for the next page. `null` when this is the last page. */
-    next_offset: number | null;
-    /** Total number of entries in the scope (across all pages). */
-    total: number;
-}
-/** Shallow runtime guard for {@link DataListResponse}. */
-declare function isDataListResponse(value: unknown): value is DataListResponse;
-/** Response for `org-data-get`. */
-interface DataGetResponse {
-    entry_id: string;
-    /** Hex-encoded raw payload bytes. */
-    payload_hex: string;
+declare class SessionExpiredError extends T3nError {
+    constructor(cause: unknown);
 }
-/** Shallow runtime guard for {@link DataGetResponse}. */
-declare function isDataGetResponse(value: unknown): value is DataGetResponse;
 /**
- * Legacy direct-route org-data envelope shape retained for compatibility.
+ * Error thrown during RPC communication.
  *
- * This mirrors the removed `/api/user-contract/execute` body format from
- * the transitional transport. New callers should use `OrgDataClient`,
- * which now dispatches through authenticated `/api/rpc` +
- * `action.execute` instead.
+ * `message` is the human-readable error (preferring the server's
+ * `error.data.detail` when present, with the request id appended in
+ * `[<id>]` form so a UI that only surfaces `.message` still gives an
+ * operator something to grep). The structured fields below preserve
+ * the same info for callers that want to render or log them
+ * separately — e.g. a toast that shows `detail` but surfaces
+ * `requestId` in a "copy for support" affordance.
  */
-interface OrgDataActionWire {
-    nonce: string;
-    user_did: string;
-    authenticator_id: string;
-    contract_id: string;
-    function: string;
-    args_hash: string;
-    expires_at_secs: number;
-    signature: string;
+declare class RpcError extends T3nError {
+    readonly rpcMethod?: string | undefined;
+    readonly httpStatus?: number | undefined;
+    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
+     *  carry the specific reason here; internal kinds omit it. */
+    readonly detail?: string | undefined;
+    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
+    readonly requestId?: string | undefined;
+    constructor(message: string, rpcMethod?: string | undefined, httpStatus?: number | undefined, 
+    /** Server-attached detail (JSON-RPC `error.data.detail`). User-facing kinds
+     *  carry the specific reason here; internal kinds omit it. */
+    detail?: string | undefined, 
+    /** Per-request correlation id (JSON-RPC `error.data.request_id`). */
+    requestId?: string | undefined);
 }
-
 /**
- * Token-metering wire shapes.
+ * Error thrown when an OTP send is throttled by the node.
  *
- * Mirrors the token-metering wire contract. `u128` fields land on the
- * wire as JSON numbers (same convention as the existing
- * `token.get-balance` response) — JS clients with histories that
- * exceed 2⁵³ tokens should switch to a streaming JSON parser; the
- * common case fits in `number` losslessly.
- */
-/**
- * The token `BalanceRow` wire shape — caller's credit row.
+ * The email-OTP login flow's `InitEmailOtp` step refuses a send when a
+ * still-valid code was issued within the resend cooldown
+ * (`reason: "cooldown_active"`) or the rolling per-recipient send cap is
+ * exhausted (`reason: "send_cap_exceeded"`). Previously a cooldown-
+ * suppressed resend returned a silent success, leaving a user who never
+ * received the first code at a dead end; this typed error lets the app
+ * render a "you just requested a code — retry in {retryAfterSecs}s"
+ * affordance instead.
  *
- * `available` and `reserved` are `u128` on the server; the wire
- * format is a JSON number. Callers should not assume bigint until
- * the SDK migrates to a streaming parser (tracked separately).
+ * Recognised from the node's stable
+ * `OtpRateLimited (reason=…, retry_after_secs=…)` wire token (pinned by a
+ * server-side test). Subclass of {@link RpcError} so callers that catch
+ * the parent still see `httpStatus`/`requestId`; callers that want the
+ * typed surface `instanceof OtpRateLimitedError` to read `reason` and
+ * `retryAfterSecs`.
  *
- * ⚠️ Amounts are in **base units** (`1 token = `
- * {@link BASE_UNITS_PER_TOKEN}), not whole tokens. Use
- * {@link formatTokens} to display them.
+ * Retryable after `retryAfterSecs` (caller-side back-off).
  */
-interface BalanceRow {
-    /** Spendable balance, in base units (see {@link formatTokens}). */
-    available: number;
-    /** Reserved balance, in base units. */
-    reserved: number;
-    last_settled_seq_no: number;
-    version: number;
-    credit_exhausted: boolean;
+declare class OtpRateLimitedError extends RpcError {
+    /** Stable reason code: `"cooldown_active"` or `"send_cap_exceeded"`. */
+    readonly reason: string;
+    /** Seconds to wait before retrying the send (parsed from `retry_after_secs=`). */
+    readonly retryAfterSecs: number;
+    constructor(message: string, 
+    /** Stable reason code: `"cooldown_active"` or `"send_cap_exceeded"`. */
+    reason: string, 
+    /** Seconds to wait before retrying the send (parsed from `retry_after_secs=`). */
+    retryAfterSecs: number, rpcMethod?: string, requestId?: string);
 }
 /**
- * The token-tx-kind wire alphabet (snake_case). Every
- * value listed here is accepted by the server-side
- * `token.get-usage` `kinds` filter.
- */
-type TokenTxKind = "mint" | "burn" | "charge" | "transfer" | "bridge_mint_attest" | "bridge_burn_attest";
-/**
- * Per-caller view direction. `"in"` = caller's balance went up;
- * `"out"` = caller's balance went down. Derived host-side from
- * `(caller_did, tx.src, tx.dst)`; the same `seq_no` appears in both
- * parties' usage feeds with opposite directions on a transfer.
- */
-type Direction = "in" | "out";
-/**
- * Discriminated union mirroring the charge-reason wire union.
- * Present only when the row's `kind === "charge"`.
- */
-type ChargeReason = {
-    kind: "contract_register";
-    script_name: string;
-    version: string;
-} | {
-    kind: "invocation";
-    script_name: string;
-    function: string;
-    fuel_consumed: number;
-    fuel_tokens: number;
-    host_call_count: number;
-    host_call_tokens: number;
-} | {
-    kind: "kv_bytes";
-    map: string;
-} | {
-    kind: "cas_bytes";
-    backend: string;
-} | {
-    kind: "outbox_egress";
-    upstream: string;
-};
-/**
- * One row in the caller's usage feed — a per-caller projection of
- * the underlying `TokenTx`. `counterparty` is the other party from
- * the caller's perspective: `tx.dst` on outbound entries, `tx.src`
- * on inbound. `null` when the underlying tx has no counterparty
- * (mints have no `src`; burns and charges have no `dst`).
+ * Error thrown when WASM operations fail
  */
-interface UsageEntry {
-    seq_no: number;
-    kind: TokenTxKind;
-    /** Amount moved, in base units (`1 token = `{@link BASE_UNITS_PER_TOKEN}); see {@link formatTokens}. */
-    amount: number;
-    timestamp_ms: number;
-    direction: Direction;
-    counterparty?: string | null;
-    reason?: ChargeReason | null;
-    note?: string | null;
+declare class WasmError extends T3nError {
+    readonly operation?: string | undefined;
+    readonly payload?: unknown | undefined;
+    constructor(message: string, operation?: string | undefined, payload?: unknown | undefined);
 }
 /**
- * Response shape of `token.get-usage` — caller's balance plus a
- * paginated slice of their most-recent `token:tx_log` entries.
+ * Decode WASM error message from comma-separated byte array format
+ * WASM errors often come as "83,101,114,100,101..." which represents ASCII bytes
  *
- * `next_cursor` is the inclusive upper-bound `seq_no` to pass back
- * as `after_seq` to fetch the next page. `null` (or absent) means
- * the caller's history is fully drained.
+ * @param errorMessage - The error message string that may contain comma-separated bytes
+ * @returns Decoded error message if it was encoded, otherwise original message
  */
-interface UsagePage {
-    balance: BalanceRow;
-    entries: UsageEntry[];
-    next_cursor?: number | null;
-}
+declare function decodeWasmErrorMessage(errorMessage: string): string;
 /**
- * Request shape — all fields optional. `limit` clamps to
- * `1..=200` server-side; out-of-range values snap silently to the
- * bounds. `kinds: []` is treated as "no filter".
+ * Extract and decode error from WASM ComponentError
+ *
+ * @param error - The error object from WASM
+ * @returns Decoded error message
  */
-interface GetUsageOptions {
-    limit?: number;
-    after_seq?: number;
-    kinds?: TokenTxKind[];
-}
+declare function extractWasmError(error: unknown): string;
 
 /**
- * Tenant audit-event wire shapes.
+ * Contract response decoding for {@link T3nClient.execute}.
  *
- * Mirrors `tenant_types::AuditEvent` and the `audit.get-mine` response
- * (`service::tenant_logs::{AuditBatch, AuditPage}`). A tenant contract
- * emits an audit event via the `logging::audit` host call; the host
- * stamps the identity fields (`subject` / `actor` / `vc_id`) from the
- * verified dispatch context, so a contract can never forge who acted or
- * on whom. Events are permanent (encrypted, append-only) and scoped to a
- * user — distinct from the evicting debug ring read via `getContractLogs`.
+ * ## On-wire shape
+ *
+ * Trinity contracts are declared as `result<list<u8>, string>` in WIT and
+ * return JSON-encoded bytes. The server-side pipeline is:
+ *
+ * 1. The contract's returned bytes are deserialized into a JSON `Value`
+ *    (the contract's decoded return value).
+ * 2. The host wraps that value in an internal `ContractResponse` struct
+ *    for bookkeeping — it carries an extracted `otp_state` alongside the
+ *    response.
+ * 3. The host then unwraps the struct, discarding the `otp_state` field
+ *    and returning only the inner `Value` across the executor boundary.
+ * 4. That plain `Value` is serialised through the session channel.
+ *
+ * The client therefore receives the contract's **decoded JSON value
+ * directly** — no `{response, otp_state}` envelope, despite what the
+ * struct name suggests. `parseContractResponse` reflects that reality:
+ * it does a typed `JSON.parse` with optional schema validation, nothing
+ * more. OTP flows read their `otp_status` / OTP fields directly off the
+ * contract's response body; there is no separate envelope field for them
+ * on this path.
  */
+
 /**
- * One host-stamped audit event. `subject` / `actor` are canonical DID
- * strings. On a self-call `actor === subject` and `vc_id` is `null`; on a
- * delegated call `actor` is the agent and `vc_id` is the delegation
- * credential. The remaining fields are supplied verbatim by the contract.
+ * Minimal validator interface. Any library that exposes `.parse(value) -> T`
+ * (zod, valibot, superstruct, custom) is compatible.
  */
-interface AuditEvent {
-    /** Cluster-deterministic flush timestamp (ms). */
-    ts_ms: number;
-    /** The user whose data the call touched (host-stamped `pii_did`). */
-    subject: string;
-    /** The agent (delegated) or user (self-call) who acted (host-stamped). */
-    actor: string;
-    /** Delegation credential id on a delegated call; `null` on a self-call. */
-    vc_id?: string | null;
-    /** Contract-supplied: what happened, e.g. `"kyc.approve"`. */
-    action: string;
-    /** Contract-supplied: what it acted on, e.g. `"user-profile"`. */
-    target: string;
-    /** Contract-supplied: the result, e.g. `"success"` / `"denied"`. */
-    outcome: string;
-    /** Contract-supplied: optional free-text / JSON detail. */
-    details?: string | null;
+interface ContractResponseSchema<T> {
+    parse(value: unknown): T;
 }
 /**
- * One archived batch — the events committed in a single tenant dispatch.
- * Every event in a batch shares the same `subject` / `actor` / `vc_id`.
+ * Thrown when the response string from {@link T3nClient.execute} cannot
+ * be parsed as JSON.
+ *
+ * Schema-validation failures are NOT wrapped — they surface as whatever
+ * error the caller's validator throws, preserving the rich diagnostics
+ * those libraries already provide.
  */
-interface AuditBatch {
-    /** Hex of the archive key — usable directly as `cursor` for the next page. */
-    key: string;
-    /**
-     * Host-stamped: did the emitting dispatch's contract transaction
-     * commit? `false` means the call rolled back or trapped, so an event's
-     * `outcome: "success"` in this batch is the contract's *claim*, not a
-     * committed fact — filter on this when you need only durable events.
-     */
-    committed: boolean;
-    events: AuditEvent[];
+declare class ContractResponseError extends T3nError {
+    readonly raw?: string | undefined;
+    constructor(message: string, raw?: string | undefined);
 }
 /**
- * `audit.get-mine` response — a page of audit batches, newest scan order.
- * `next_cursor` is present (a key hex) when more batches remain; `null`
- * once the scan reaches the end.
+ * Parse the JSON-encoded response returned by {@link T3nClient.execute}
+ * into a typed value.
+ *
+ * @param raw - the string returned by {@link T3nClient.execute}
+ * @param schema - optional validator applied to the parsed value
+ * @returns the decoded response, typed as `T`
+ * @throws {ContractResponseError} when `raw` is not valid JSON
+ * @throws whatever the schema throws on validation failure (e.g. `ZodError`)
  */
-interface AuditPage {
-    batches: AuditBatch[];
-    next_cursor?: string | null;
-}
+declare function parseContractResponse<T = unknown>(raw: string, schema?: ContractResponseSchema<T>): T;
+
 /**
- * Request shape for {@link T3nClient.getAuditEvents} — all fields
- * optional. Omit `pii_did` to read your own trail (all actors); set it to
- * another user's DID to read, as a delegated agent, the events you
- * performed for them — admitted only while that user's agent-auth grant
- * to you is live. `cursor` is the `next_cursor` from a prior page.
+ * Agent-auth grants — the standing on-chain authority a user delegates to
+ * an agent (envelope-free authorisation).
+ *
+ * `AGENT_AUTH_MAP` is keyed by the *user* DID — one policy document per
+ * user, global across orgs, with at most one entry per agent DID. Reads
+ * (`agent-auth-get`) and writes (`agent-auth-update`) on
+ * `tee:user/contracts` are **SelfOnly**: only the user, authenticated as
+ * themselves, may read or write their own grants. This is the user-approval
+ * proof the per-call delegation credential's `user_sig` used to carry.
+ *
+ * The write shape gained `scopes` + a validity window: the
+ * agent's delegated org-data scopes, and an optional `[valid_from_secs,
+ * valid_until_secs]` window. The ≤ cap *length* check is enforced contract-
+ * side at write time; the expiry gate is host-side at read time.
+ *
+ * The merge below is a script-level union (R59): writing a grant for one
+ * `(agent_did, script_name)` preserves every other script row on that
+ * agent's entry, and every other agent's entry, unchanged.
  */
-interface GetAuditEventsOptions {
-    pii_did?: string;
-    limit?: number;
-    cursor?: string;
+/** A single script grant in the camelCase write-request shape. */
+interface AgentAuthScriptGrant {
+    /** Contract name, or `"*"`. */
+    scriptName: string;
+    /** Optional semver requirement; `null` to match any version. */
+    versionReq?: string | null;
+    /** Functions the agent may invoke on this contract. */
+    functions: string[];
+    /** Org-data scopes delegated to the agent for the contract functions to
+     *  read on its behalf. */
+    scopes?: string[];
+    /** Direct-read scopes the agent may enumerate itself, via whichever read
+     *  function the contract exposes for direct enumeration. A strict subset of
+     *  `scopes` (enforced contract-side). */
+    readScopes?: string[];
+    /** Optional validity-window start (unix seconds). */
+    validFromSecs?: number | null;
+    /** NEW: optional validity-window end (unix seconds). */
+    validUntilSecs?: number | null;
+    /** Egress hosts the agent may reach for this contract. */
+    allowedHosts: string[];
+}
+/** One agent's entry in the write-request shape. */
+interface AgentAuthEntry {
+    agentDid: string;
+    scripts: AgentAuthScriptGrant[];
 }
-
-/**
- * Public types export for T3n SDK
- */
 /**
- * Guest-to-Host request handler function type
+ * The full agent-auth policy document in the camelCase write shape:
+ * the per-agent grants plus the document-level discovery grants.
  *
- * Handles requests from WASM guest that need host (SDK) to perform side
- * effects. The exact shape of `requestData` depends on the specific
- * handler — see `GuestToHostHandlers` below for the per-handler shapes.
- * The wrapper layer in `T3nClient.handleGuestToHost` parses the JSON
- * envelope and calls the matching handler with the parsed data, so
- * each handler's implementation should narrow `requestData` to its
- * own expected shape.
+ * `discoverDids` (contract wire: `discover_dids`) is the
+ * list of DIDs the user lets their registered agents *enumerate the
+ * contracts of* via `listContracts`: an org DID grants org-mode discovery,
+ * the user's own DID grants self-mode discovery. It lives at document
+ * level — not on a script grant — because discovery must surface contracts
+ * the agent cannot yet call. The node's discovery gate additionally
+ * requires the calling agent to be named in `agents` (subject binding), so
+ * an unregistered agent discovers nothing regardless of this list.
  */
-type GuestToHostHandler = (requestData: Record<string, unknown>) => Promise<Uint8Array>;
+interface AgentAuthPolicy {
+    agents: AgentAuthEntry[];
+    discoverDids: string[];
+}
 /**
- * Map of guest-to-host request handlers
- * Keys match the guest_to_host tag values from the WASM
+ * Parse a full `agent-auth-get` response (the stored snake_case policy
+ * document) into the camelCase write shape, including the document-level
+ * `discover_dids`. A `null` / absent response is the empty policy.
  */
-interface GuestToHostHandlers {
-    /**
-     * Handle Ethereum signature requests
-     * requestData: { guest_to_host: "EthSign", challenge: string (base64) }
-     * Returns: JSON bytes of { host_to_guest: "EthSign", challenge: string, signature: string }
-     */
-    EthSign?: GuestToHostHandler;
-    /**
-     * Handle MlKem public key requests
-     * requestData: { guest_to_host: "MlKemPublicKey" }
-     * Returns: JSON bytes of { host_to_guest: "MlKemPublicKey", key: string }
-     */
-    MlKemPublicKey?: GuestToHostHandler;
-    /**
-     * Handle random bytes requests
-     * requestData: { guest_to_host: "Random", len?: number }
-     * Returns: JSON bytes of { host_to_guest: "Random", bytes: string (base64) }
-     */
-    Random?: GuestToHostHandler;
-    [key: string]: GuestToHostHandler | undefined;
+declare function parseAgentAuthPolicy(response: unknown): AgentAuthPolicy;
+/** Extract the `agents` array from an `agent-auth-get` response. */
+declare function parseAgentAuthGet(response: unknown): AgentAuthEntry[];
+interface AgentAuthMergeResult {
+    /** Full merged `agents` list, ready for `agent-auth-update`. */
+    agents: AgentAuthEntry[];
+    /** `"<agentDid> → <scriptName>"` rows preserved from the existing policy. */
+    preservedRows: string[];
+}
+/** Input to the full-document write {@link T3nClient.agentAuthUpdate}. The
+ *  document IS the new state: an empty `agents` list revokes all agent
+ *  access, and an omitted / empty `discoverDids` persists an empty
+ *  discovery-grant list (the contract has no per-field merge). Mirrors the
+ *  contract `AgentAuthPolicy`. */
+interface AgentAuthUpdateInput {
+    agents: AgentAuthEntry[];
+    /** Document-level discovery grants — see {@link AgentAuthPolicy}. */
+    discoverDids?: string[];
 }
-
 /**
- * Transport layer for T3n SDK
- *
- * Abstracts the communication with T3n nodes, allowing for different
- * implementations (HTTP, WebSocket, Mock) and easy testing.
+ * Serialise a camelCase policy document to the contract's canonical
+ * snake_case `agent-auth-update` wire (`agent_did` / `script_name` /
+ * `version_req` / `read_scopes` / `valid_from_secs` / `valid_until_secs` /
+ * `allowed_hosts` / `discover_dids`), so neither write path relies on the
+ * contract's compatibility aliases. Absent optionals are omitted (never
+ * sent as `null`); empty `scopes` / `read_scopes` are omitted (the
+ * contract defaults both to empty). `functions` and `allowed_hosts` are
+ * always emitted — the contract requires explicit functions (`["*"]` =
+ * all) and reads an absent `allowed_hosts` as deny-all egress. The
+ * document-level `discover_dids` (strictly snake_case — the contract
+ * defines no camelCase alias for it) is emitted only when non-empty; the
+ * contract defaults an absent list to empty.
  */
+declare function toAgentAuthUpdateWire(agents: AgentAuthEntry[], discoverDids?: string[]): {
+    agents: Array<{
+        agent_did: string;
+        scripts: Array<Record<string, unknown>>;
+    }>;
+    discover_dids?: string[];
+};
 /**
- * JSON-RPC request structure
+ * Order-preserving deduplicating union of discovery-grant DID lists —
+ * the read-merge-write counterpart of {@link mergeAgentAuthEntries} for
+ * the document-level `discoverDids` (the contract rejects duplicate
+ * entries, so the union must dedupe).
  */
-interface JsonRpcRequest {
-    jsonrpc: "2.0";
-    method: string;
-    params: unknown;
-    id: string | number;
-}
+declare function mergeDiscoverDids(existing: string[], additions: string[]): string[];
 /**
- * JSON-RPC response structure
+ * Merge new agent entries into the existing policy with script-level union
+ * semantics: for an agent DID present on both sides, script rows whose
+ * `scriptName` is not being written are preserved; rows with a matching
+ * `scriptName` are replaced by the new grant. Entries for other agent DIDs
+ * pass through unchanged.
  */
-interface JsonRpcResponse {
-    jsonrpc: "2.0";
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-        data?: unknown;
-    };
-    id: string | number;
-}
+declare function mergeAgentAuthEntries(existing: AgentAuthEntry[], newEntries: AgentAuthEntry[]): AgentAuthMergeResult;
+
 /**
- * Transport interface for sending requests to T3n nodes
+ * KYC types for the `tee:user/contracts::kyc-status` short-poll
+ * function.
+ *
+ * The shape mirrors the `kyc-status` wire response.
+ * The bytes go straight from the contract
+ * through the JSON-RPC envelope into [[T3nClient.kycStatus]].
  */
-interface Transport {
-    /**
-     * Send a JSON-RPC request to the T3n node
-     * @param request - The JSON-RPC request to send
-     * @param headers - Additional headers to include
-     * @returns Promise that resolves to the JSON-RPC response
-     */
-    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
-    /**
-     * Send a JSON-RPC request with an attached binary blob (multipart/form-data).
-     * Part 1 (name=jsonrpc): JSON-RPC envelope.
-     * Part 2 (name=blob): raw binary bytes (e.g. WASM bytecode).
-     */
-    sendMultipart?(request: JsonRpcRequest, headers: Record<string, string>, blob: Blob): Promise<JsonRpcResponse>;
-    /**
-     * Optional accessor for the latest Set-Cookie header value.
-     * (Useful in Node.js demos/tests; browsers block HttpOnly cookies.)
-     */
-    getLastSetCookie?(): string | null;
-    /**
-     * Optional accessor for the last response headers (debugging).
-     */
-    getLastResponseHeaders?(): Record<string, string>;
-}
+
 /**
- * HTTP transport implementation using fetch
+ * Terminal status for a Level 2 KYC verification, plus `pending`.
+ *
+ * - `pending` — provider has not delivered a verdict yet, or the
+ *   webhook arrived but the post-action VC issuance hasn't completed.
+ * - `verified` — provider approved AND a VC has been issued. `vcIds`
+ *   carries the issued credential ids.
+ * - `rejected` — provider declined / required resubmission /
+ *   expired / the user abandoned the flow. `error` may carry a
+ *   provider-supplied reason.
+ * - `orphan` — a Veriff webhook arrived with a `vendorData` that
+ *   couldn't be matched to any user. Should not
+ *   happen in the MetaMask flow but the contract surfaces it for
+ *   completeness.
  */
-declare class HttpTransport implements Transport {
-    private baseUrl;
-    private timeout;
-    private lastSetCookie;
-    private lastResponseHeaders;
-    /**
-     * Cookie jar (`name -> value`) for non-browser callers. The session is
-     * node-local in-memory state, so once the load balancer pins a client
-     * to a node via its `GCLB` session-affinity cookie, every later request
-     * in the session must carry that cookie back or it gets re-balanced to
-     * a node that has never seen the handshake → `401 session not found`.
-     * Browsers replay the cookie automatically from their own jar (via
-     * `credentials: "include"`); plain `fetch` callers (Node demos, tests,
-     * server-side SDK usage) have no jar, so we keep one here. Empty in
-     * browsers — there `getSetCookie()` is unavailable and a script-set
-     * `Cookie` header is forbidden, so this stays inert.
-     */
-    private cookieJar;
-    constructor(baseUrl: string, timeout?: number);
-    getLastSetCookie(): string | null;
-    getLastResponseHeaders(): Record<string, string>;
-    /**
-     * Record response headers and merge any `Set-Cookie` into the jar.
-     *
-     * undici's `Headers` exposes `getSetCookie()` (one entry per cookie);
-     * the DOM `Headers` type doesn't declare it, so cast structurally. In
-     * browsers neither `getSetCookie()` nor reading `set-cookie` is
-     * permitted, so `setCookies` is empty and the jar is left untouched.
-     */
-    private captureResponseMetadata;
-    /**
-     * Build a `Cookie` request header from the jar so non-browser callers
-     * stay pinned to the node holding their session. Returns `{}` when the
-     * jar is empty — always the case in browsers, leaving their native
-     * cookie handling untouched.
-     *
-     * `callerHeaders` is checked case-insensitively: if the caller already
-     * supplied a `Cookie`/`cookie` header, the jar yields to it entirely.
-     * (Object spread keys are case-sensitive, but `fetch`'s `Headers` are
-     * not — emitting `Cookie` here while the caller passed `cookie` would
-     * make the two coexist and get comma-combined instead of overridden.)
-     */
-    private cookieHeader;
-    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
-    sendMultipart(request: JsonRpcRequest, headers: Record<string, string>, blob: Blob): Promise<JsonRpcResponse>;
-}
+type KycStatusKind = "pending" | "verified" | "rejected" | "orphan";
 /**
- * Mock transport for testing
- *
- * @example
- * ```typescript
- * const mockTransport = new MockTransport();
- * mockTransport.mockResponse("auth.handshake", { result: "..." });
+ * Snapshot returned by `tee:user/contracts::kyc-status`.
  *
- * const client = new T3nClient({
- *   trustAnchor: { unsafe_trust_server: true },
- *   transport: mockTransport,
- *   wasmComponent: mockWasm,
- * });
- * ```
+ * Field names use camelCase on the SDK boundary even though the
+ * wire is snake_case — the wrapper rewrites keys at the client edge
+ * so callers don't see the JSON shape leaking through.
  */
-declare class MockTransport implements Transport {
-    private responses;
-    private responseHeaders;
-    private lastResponseHeaders;
-    private requests;
-    private multipartRequests;
-    /**
-     * Mock a response for a specific method
-     */
-    mockResponse(method: string, response: Partial<JsonRpcResponse>): void;
-    /**
-     * Mock response headers for a specific method. Used by tests to
-     * simulate the server-minted `Session-Id` header the SDK picks up
-     * from the `auth.handshake` response. Unset methods
-     * default to no headers.
-     */
-    mockResponseHeaders(method: string, headers: Record<string, string>): void;
+interface KycStatus {
+    /** Terminal status if reached, otherwise `pending`. */
+    status: KycStatusKind;
     /**
-     * Mock an error response for a specific method
+     * Provider being polled. Echoed back so callers that didn't
+     * supply one see the contract's default (`"veriff"` in phase one).
      */
-    mockError(method: string, code: number, message: string, data?: unknown): void;
-    getLastResponseHeaders(): Record<string, string>;
+    provider: string;
     /**
-     * Get all requests that were sent
+     * Unix-millis of the latest contract-visible event:
+     * VC issuance time, attestation arrival time, session-row
+     * `started_at_ms`, or orphan-record arrival time. Best-effort —
+     * `undefined` when no source carries a usable timestamp.
      */
-    getRequests(): Array<{
-        request: JsonRpcRequest;
-        headers: Record<string, string>;
-    }>;
+    updatedAt?: number;
     /**
-     * Get requests for a specific method
+     * VC ids appended for this provider, in append order. Empty for
+     * `pending` / `rejected` / `orphan`.
      */
-    getRequestsForMethod(method: string): Array<{
-        request: JsonRpcRequest;
-        headers: Record<string, string>;
-    }>;
-    getMultipartRequests(): Array<{
-        request: JsonRpcRequest;
-        headers: Record<string, string>;
-        blob: Blob;
-    }>;
+    vcIds: string[];
     /**
-     * Clear all recorded requests
+     * Provider-supplied reason for `rejected`, when available.
      */
-    clearRequests(): void;
-    sendMultipart(request: JsonRpcRequest, headers: Record<string, string>, blob: Blob): Promise<JsonRpcResponse>;
-    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
+    error?: string;
 }
-
 /**
- * TDX quote verifier backed by the Rust `signature` crate compiled to
- * WASM. Full cryptographic verification: ECDSA P-256 attestation-key
- * signature, PCK certificate chain walk to Intel's root CA, and
- * report_data + RTMR comparison.
- *
- * The WASM bytes are inlined as base64 (see quote_verifier_bytes.ts)
- * so the SDK works without bundler WASM plugins and without runtime
- * asset URL resolution.
+ * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults:
+ * poll fast for the first 30 seconds, then back
+ * off, and bail after 5 minutes.
  */
-interface QuoteVerifyResult {
-    valid: boolean;
-    error?: string;
-    rtmr3?: string;
-    report_data?: string;
-}
-interface PeerQuoteResult {
-    peer_id: string;
-    valid: boolean;
-    error?: string;
-    rtmr3?: string;
-}
-interface DkgVerifyResult {
-    valid: boolean;
-    results: PeerQuoteResult[];
-    valid_count: number;
-    expected_count: number;
-    error?: string;
+interface KycPollCadence {
+    /** Poll interval in ms while `elapsed < switchAtMs`. Default: 2000. */
+    fastMs: number;
+    /** Poll interval in ms once `elapsed >= switchAtMs`. Default: 5000. */
+    slowMs: number;
+    /** Elapsed-ms threshold to switch from fast to slow cadence. Default: 30_000. */
+    switchAtMs: number;
+    /**
+     * Maximum total time to spend polling before rejecting with
+     * [[KycStatusTimeoutError]]. Default: 300_000 (5 minutes).
+     */
+    timeoutMs: number;
 }
 /**
- * Client-pinned anchor the DKG attestation bundle is verified against.
- *
- * Without it, "the server proved it runs in a TEE" only means "*some*
- * TDX box somewhere" — any attacker with their own TDX cloud VM can
- * forge a complete, cryptographically-valid bundle for their own key
- * (SP-003). The anchor is the independent ground truth that closes it:
- * the bundle must describe *our* cluster (`expected_peer_ids`) running
- * *our* image (`rtmr3_allowlist`).
+ * Optional knobs for [[T3nClient.kycStatusPoll]]. Most callers won't
+ * touch any of these — the cadence defaults are baked in.
  */
-interface TrustAnchor {
+interface KycPollOptions {
     /**
-     * Base58 peer IDs the client expects in the cluster. The bundle's
-     * `peer_ids` must equal this set exactly (order-insensitive) — a MITM
-     * cannot substitute its own single-node participant set.
+     * Cancellation signal. When aborted, the helper rejects with
+     * `signal.reason` (or a generic `AbortError` if the consumer
+     * didn't supply a reason). The currently-in-flight `kycStatus()`
+     * call also receives the signal so it can short-circuit.
      */
-    expected_peer_ids: string[];
+    signal?: AbortSignal;
     /**
-     * Base64-encoded 48-byte RTMR3 measurements of the expected node
-     * image. Every quote's RTMR3 must be a member. **Must be non-empty.**
-     * An array (not a singleton) so a rolling deploy's two in-flight
-     * image measurements both verify.
+     * Called with every snapshot the helper receives, including
+     * non-terminal `pending` ones. Useful for surfacing intermediate
+     * UI states (e.g. "still waiting on provider…"). Errors thrown
+     * from this callback are caught and ignored — they must not
+     * sink the poll loop.
      */
-    rtmr3_allowlist: string[];
+    onUpdate?: (status: KycStatus) => void;
+    /**
+     * Override one or more cadence fields. Anything not specified
+     * uses the defaults from [[DEFAULT_KYC_POLL_CADENCE]].
+     */
+    cadence?: Partial<KycPollCadence>;
+    /**
+     * Provider id to poll. Defaults to the contract default
+     * (`"veriff"` in phase one). Mirrored on the wire as
+     * `input.provider_id`.
+     */
+    providerId?: string;
 }
 /**
- * Escape hatch for local dev / tests against a node whose attestation
- * can't be anchored (e.g. a mock signer that publishes no bundle).
- *
- * The name is deliberately alarming so it stands out in code review and
- * grep — it is the *only* way to skip DKG attestation verification on
- * the handshake path.
+ * Default cadence used by [[T3nClient.kycStatusPoll]] when the caller
+ * doesn't override `cadence.*`.
  */
-interface UnsafeTrustServer {
-    unsafe_trust_server: true;
+declare const DEFAULT_KYC_POLL_CADENCE: KycPollCadence;
+/**
+ * Subset of [[KycStatusKind]] that ends a poll. `pending` is the
+ * only non-terminal value.
+ */
+declare const TERMINAL_KYC_STATUSES: ReadonlySet<KycStatusKind>;
+/**
+ * Thrown by [[T3nClient.kycStatusPoll]] when the cadence's
+ * `timeoutMs` elapses without a terminal status arriving. The
+ * `lastStatus` field is the most recent (necessarily `pending`)
+ * snapshot the helper saw, useful for surfacing "we tried for N
+ * minutes but Veriff is still working" UX.
+ */
+declare class KycStatusTimeoutError extends T3nError {
+    /** The timeout (ms) the helper exhausted before a terminal status arrived. */
+    readonly timeoutMs: number;
+    /** The last `pending` snapshot before timeout, if any. */
+    readonly lastStatus?: KycStatus | undefined;
+    constructor(
+    /** The timeout (ms) the helper exhausted before a terminal status arrived. */
+    timeoutMs: number, 
+    /** The last `pending` snapshot before timeout, if any. */
+    lastStatus?: KycStatus | undefined);
 }
-type TrustAnchorOrUnsafe = TrustAnchor | UnsafeTrustServer;
-/** Narrow a {@link TrustAnchorOrUnsafe} to the explicit opt-out arm. */
-declare function isUnsafeTrustServer(anchor: TrustAnchorOrUnsafe): anchor is UnsafeTrustServer;
+
 /**
- * Verify a single TDX attestation quote with full cryptographic verification.
+ * Wire types for the explicit `otp-request` /
+ * `otp-verify` / slim `user-upsert` exports on `tee:user/contracts`
+ * (`tee:user@2.0.0`).
  *
- * @param quoteB64 - Base64-encoded raw TDX v4 quote
- * @param attestationMsgB64 - Base64-encoded attestation message
- *   (for DKG: encaps_key || sorted_peer_id_bytes)
- * @param expectedRtmr3B64 - Optional base64-encoded 48-byte RTMR3
- * @returns Verification result with extracted measurements
+ * Pre-2.0.0 the user contract dispatched OTP request and OTP verify
+ * implicitly from the input shape of a single `user-upsert` call.
+ * 2.0.0 splits that surface into three explicit functions; the
+ * shapes here mirror the OTP / user-upsert wire contract.
+ *
+ * Bytes flow directly from the contract
+ * through the JSON-RPC envelope into the SDK wrappers
+ * (`T3nClient.otpRequest`, `T3nClient.otpVerify`,
+ * `T3nClient.submitUserInput`).
  */
-declare function verifyTdxQuote(quoteB64: string, attestationMsgB64: string, expectedRtmr3B64?: string): Promise<QuoteVerifyResult>;
+
 /**
- * Verify a full DKG attestation bundle against a client-pinned
- * {@link TrustAnchor}: multiple TDX quotes from all participating
- * nodes, plus the binding between the quotes and the ML-KEM
- * encapsulation key. Checks:
- *   1. `expected_peer_ids` / `rtmr3_allowlist` are both non-empty
- *   2. the bundle's `peer_ids` equal the pinned set exactly
- *   3. attestationMsg starts with encapsKey (server can't swap the key)
- *   4. every quote's ECDSA signature chains to Intel's SGX root CA
- *   5. every quote's report_data == keccak512(attestationMsg)
- *   6. every quote's RTMR3 is a member of `rtmr3_allowlist`
+ * OTP delivery channel. Matches the `OtpContactChannel` Rust enum
+ * with `serde(rename_all = "snake_case")`.
+ */
+type OtpChannel = "email" | "sms";
+/**
+ * Discriminated OTP contact target. Mirrors the Rust `OtpRequest` enum
+ * (`email_channel` / `sms_channel` on the wire). Exactly one branch is
+ * set — no parallel optional email + phone with a separate channel tag.
  *
- * The anchor is **required**: there is no unauthenticated mode. Callers
- * that genuinely want to trust the server must not call this at all —
- * see `unsafe_trust_server` on the client config, which branches around
- * the whole verify path.
+ * The legacy `keys.generic_api.otp_channel` body shadow was removed
+ * in 2.0.0 — the contract rejects calls carrying it with a
+ * `legacy_field` error.
+ */
+type OtpRequestInput = {
+    emailChannel: {
+        emailAddress: string;
+    };
+} | {
+    smsChannel: {
+        phoneNumber: string;
+    };
+};
+/**
+ * Response returned by `otp-request`. Mirrors the OTP wire response.
+ *
+ * - `contact` echoes the OTP destination so clients that race
+ *   multiple channels can correlate replies.
+ * - `expiresAtSec` is the Unix-second TTL the host minted for the
+ *   pending OTP. Absent in `skip_otp` test environments.
+ * - `status` is `"otp_pending"` on the happy path. `"otp_failed"`
+ *   only appears on retry without a fresh request — usually you
+ *   shouldn't see it on `otp-request`.
+ * - `txHash` is the host-enriched ledger ref for the OTP-pending
+ *   write (the contract leaves it `null`; the host injects).
+ * - `isNewProfile` is `true` on a fresh DID's first OTP request —
+ *   read this to detect "did the user just register".
+ */
+interface OtpRequestResult {
+    contact: string;
+    channel: OtpChannel;
+    expiresAtSec?: number;
+    status?: string;
+    txHash?: string;
+    isNewProfile?: boolean;
+}
+/**
+ * Input to `T3nClient.otpVerify`. `otpCode` is mandatory; `request`
+ * repeats the same discriminated contact shape as {@link OtpRequestInput}.
+ */
+interface OtpVerifyInput {
+    otpCode: string;
+    request: OtpRequestInput;
+}
+/**
+ * Suggestion surfaced when the bind-target contact already belongs
+ * to another DID. The contract refuses to silently steal the
+ * authenticator; the caller must resolve the merge (typically via
+ * `merge-profiles`) before re-attempting verify.
+ */
+interface OtpMergeSuggestion {
+    existingDid: string;
+    currentDid: string;
+    email?: string;
+    phone?: string;
+    channel: OtpChannel;
+}
+/**
+ * Response returned by `otp-verify`. Mirrors the OTP-verify wire response.
  *
- * @param encapsKeyB64 - Base64-encoded ML-KEM encapsulation key
- *   (from `/status.encaps_key`)
- * @param attestationMsgB64 - Base64-encoded raw attestation message
- *   (from `/status.dkg_attestation.attestation_msg`)
- * @param peerIds - Base58 peer IDs as reported by the bundle
- * @param quotes - Map of peer_id → base64-encoded TDX quote
- * @param anchor - Client-pinned expected peer IDs + RTMR3 allowlist
- * @returns Per-peer verification results and overall validity
+ * - `email` is populated on `channel = "email"` success;
+ *   `phone` on `channel = "sms"` success. Mutually exclusive on
+ *   the happy path.
+ * - `status` carries `"otp_failed"` / `"otp_expired"` on retry; the
+ *   happy path leaves it `undefined`.
+ * - `mergeSuggestion` is set when the contact-to-bind is already
+ *   owned by another DID. Wire it into your merge UX.
  */
-declare function verifyDkgAttestation(encapsKeyB64: string, attestationMsgB64: string, peerIds: string[], quotes: Record<string, string>, anchor: TrustAnchor): Promise<DkgVerifyResult>;
-
+interface OtpVerifyResult {
+    txHash?: string;
+    did: string;
+    channel: OtpChannel;
+    email?: string;
+    phone?: string;
+    status?: string;
+    mergeSuggestion?: OtpMergeSuggestion;
+    isNewProfile?: boolean;
+}
 /**
- * Configuration types for T3n Client
+ * Level-1 user-input fields accepted by the slim `user-upsert`. Field names
+ * are the on-the-wire names — `submitUserInput` sends this object verbatim,
+ * so keys must match the contract exactly (snake_case). The canonical Level-1
+ * set is the six fields below; the shape is intentionally open so callers can
+ * add provider-specific fields the contract knows how to merge.
+ *
+ * `email_address` / `phone_number` are normally bound via the OTP roundtrip
+ * before `submitUserInput`, but the contract accepts them directly here too.
  */
-
+interface UserInputProfile {
+    first_name?: string;
+    last_name?: string;
+    country_of_residence?: string;
+    document_issuance_country?: string;
+    ssn?: string;
+    address?: string;
+    email_address?: string;
+    phone_number?: string;
+    campaign_code?: string;
+    role?: string;
+    [key: string]: unknown;
+}
 /**
- * Configuration interface for T3n Client
+ * Input to `T3nClient.submitUserInput`. Maps onto the slim
+ * `user-upsert` request shape: `{ profile, organisation_did?,
+ * attestations?, keys? }`.
  */
-interface T3nClientConfig {
-    /** Base URL of the T3n node (used if transport not provided) */
-    baseUrl?: string;
-    /** WASM component instance for cryptographic operations */
-    wasmComponent: WasmComponent;
-    /** Optional transport layer - if not provided, uses HttpTransport with baseUrl */
-    transport?: Transport;
-    /** Optional request timeout in milliseconds (default: 30000) - used for HttpTransport */
-    timeout?: number;
-    /** Optional custom headers to include in requests */
-    headers?: Record<string, string>;
+interface SubmitUserInputArgs {
+    profile: UserInputProfile;
+    organisationDid?: string;
+    attestations?: unknown;
+    keys?: Record<string, unknown>;
     /**
-     * Log level for this client instance.
-     * Defaults to global log level (LogLevel.ERROR) if not specified.
-     * Use LogLevel.DEBUG for verbose logging, LogLevel.INFO for informational messages,
-     * LogLevel.WARN for warnings, or LogLevel.ERROR for errors only.
+     * KYC webhook orphan-attestation flow. When set, the contract
+     * skips the email-not-verified gate and only records the
+     * attestation if the DID has no profile yet.
+     * Most callers should leave this `undefined`.
      */
-    logLevel?: LogLevel;
-    /** Optional custom logger - if provided, overrides logLevel */
-    logger?: Logger;
-    /** Optional guest-to-host request handlers - provides custom behavior for WASM requests */
-    handlers?: GuestToHostHandlers;
+    requireExistingUser?: boolean;
     /**
-     * **Required.** Client-pinned trust anchor the node's DKG attestation
-     * is verified against before the handshake trusts its ML-KEM key
-     * (SP-003). Either a {@link TrustAnchor} (`expected_peer_ids` +
-     * `rtmr3_allowlist`) or the explicit `{ unsafe_trust_server: true }`
-     * opt-out for local dev / mock-signer nodes.
+     * Testnet self-admit. When `true`, the contract additionally
+     * runs the self-admit side-effect after the profile commit: writes
+     * the caller's DID into `idx:_tenants` + `idx:_tenant_quotas` and
+     * mints any operator-configured welcome credits. Inspect the
+     * `tenantAdmit` field on the response for the outcome.
      *
-     * Without this, a network attacker with their own TDX VM can hand the
-     * SDK a forged-but-valid attestation for a key it controls and read
-     * every session. It is a required field precisely so no caller can
-     * omit it by accident — bypassing verification must be a visible,
-     * grep-able choice.
+     * Testnet-only. Production clusters return
+     * `tenantAdmit.status = "refused"` with
+     * `reason = "not_testnet" | "self_admit_disabled" | "not_eth_derived"`.
+     * The profile commit always succeeds regardless of the inner outcome.
+     *
+     * Most callers should leave this `undefined`.
      */
-    trustAnchor: TrustAnchorOrUnsafe;
+    becomeDevTenant?: boolean;
 }
-
 /**
- * Contract response decoding for {@link T3nClient.execute}.
- *
- * ## On-wire shape
- *
- * Trinity contracts are declared as `result<list<u8>, string>` in WIT and
- * return JSON-encoded bytes. The server-side pipeline is:
- *
- * 1. The contract's returned bytes are deserialized into a JSON `Value`
- *    (the contract's decoded return value).
- * 2. The host wraps that value in an internal `ContractResponse` struct
- *    for bookkeeping — it carries an extracted `otp_state` alongside the
- *    response.
- * 3. The host then unwraps the struct, discarding the `otp_state` field
- *    and returning only the inner `Value` across the executor boundary.
- * 4. That plain `Value` is serialised through the session channel.
+ * Testnet self-admit projection from `user-upsert`. Present only
+ * when the caller set `becomeDevTenant: true` on the request.
  *
- * The client therefore receives the contract's **decoded JSON value
- * directly** — no `{response, otp_state}` envelope, despite what the
- * struct name suggests. `parseContractResponse` reflects that reality:
- * it does a typed `JSON.parse` with optional schema validation, nothing
- * more. OTP flows read their `otp_status` / OTP fields directly off the
- * contract's response body; there is no separate envelope field for them
- * on this path.
- */
-
-/**
- * Minimal validator interface. Any library that exposes `.parse(value) -> T`
- * (zod, valibot, superstruct, custom) is compatible.
+ * - `status: "admitted"` — first call for this DID; tenant record
+ *   committed and (if configured) welcome credits minted into
+ *   `grantedCredits`.
+ * - `status: "already-admitted"` — replay; idempotent no-op.
+ * - `status: "refused"` — the cluster declined the self-admit;
+ *   `reason` is the machine-readable cause (`not_testnet`,
+ *   `self_admit_disabled`, `not_eth_derived`), `detail` is a
+ *   human-readable string.
  */
-interface ContractResponseSchema<T> {
-    parse(value: unknown): T;
+type TenantAdmitStatus = "admitted" | "already-admitted" | "refused";
+interface TenantAdmitProjection {
+    status: TenantAdmitStatus;
+    grantedCredits?: string;
+    reason?: string;
+    detail?: string;
 }
 /**
- * Thrown when the response string from {@link T3nClient.execute} cannot
- * be parsed as JSON.
- *
- * Schema-validation failures are NOT wrapped — they surface as whatever
- * error the caller's validator throws, preserving the rich diagnostics
- * those libraries already provide.
+ * Response shape returned by the slim `user-upsert`. Carries the
+ * post-merge tx hash plus the Level-1 merge diagnostics
+ * (`refusedFields`, `mergeSuggestion`) the pre-2.0.0 omnibus
+ * `UpsertResponse` already surfaced.
  */
-declare class ContractResponseError extends T3nError {
-    readonly raw?: string | undefined;
-    constructor(message: string, raw?: string | undefined);
+interface SubmitUserInputResult {
+    txHash?: string;
+    refusedFields?: string[];
+    mergeSuggestion?: OtpMergeSuggestion;
+    userFound?: boolean;
+    /**
+     * Testnet self-admit projection. Present only when the caller
+     * set `becomeDevTenant: true` on the request.
+     */
+    tenantAdmit?: TenantAdmitProjection;
 }
 /**
- * Parse the JSON-encoded response returned by {@link T3nClient.execute}
- * into a typed value.
+ * Discriminator for {@link UserUpsertError}. Mirrors the
+ * `UserUpsertError` wire enum and its `<code>:<detail>` wire
+ * format. Branch with a `switch` over `kind`.
  *
- * @param raw - the string returned by {@link T3nClient.execute}
- * @param schema - optional validator applied to the parsed value
- * @returns the decoded response, typed as `T`
- * @throws {ContractResponseError} when `raw` is not valid JSON
- * @throws whatever the schema throws on validation failure (e.g. `ZodError`)
+ * - `EmailNotVerified` — the slim `user-upsert` was called against
+ *   a DID that has no verified email and no proving authenticator.
+ *   Run `otpRequest` + `otpVerify` first (or accept an
+ *   OIDC/Email-authed session).
+ * - `LegacyField` — caller passed a pre-2.0.0 dispatch field
+ *   (`otp_code` to a non-verify export, or
+ *   `keys.generic_api.otp_channel` anywhere). Migrate the call
+ *   site to the new explicit functions.
+ * - `UserNotFound` — `requireExistingUser` was set but no profile
+ *   exists for the DID. The attestation is recorded for audit;
+ *   no profile created.
  */
-declare function parseContractResponse<T = unknown>(raw: string, schema?: ContractResponseSchema<T>): T;
-
+type UserUpsertErrorKind = "EmailNotVerified" | "LegacyField" | "UserNotFound";
 /**
- * Agent-auth grants — the standing on-chain authority a user delegates to
- * an agent (envelope-free authorisation).
- *
- * `AGENT_AUTH_MAP` is keyed by the *user* DID — one policy document per
- * user, global across orgs, with at most one entry per agent DID. Reads
- * (`agent-auth-get`) and writes (`agent-auth-update`) on
- * `tee:user/contracts` are **SelfOnly**: only the user, authenticated as
- * themselves, may read or write their own grants. This is the user-approval
- * proof the per-call delegation credential's `user_sig` used to carry.
- *
- * The write shape gained `scopes` + a validity window: the
- * agent's delegated org-data scopes, and an optional `[valid_from_secs,
- * valid_until_secs]` window. The ≤ cap *length* check is enforced contract-
- * side at write time; the expiry gate is host-side at read time.
+ * Typed wrapper for the `<code>:<detail>` errors the slim
+ * `user-upsert` and the OTP entry points emit. `kind` is the
+ * structured discriminator the SDK derives from the error code
+ * prefix; `code` and `detail` retain the wire components for
+ * fall-through logging.
  *
- * The merge below is a script-level union (R59): writing a grant for one
- * `(agent_did, script_name)` preserves every other script row on that
- * agent's entry, and every other agent's entry, unchanged.
+ * Throw site: `T3nClient.submitUserInput` (and friends) when the
+ * contract returns a string error matching the
+ * `<code>:<detail>` shape.
  */
-/** A single script grant in the camelCase write-request shape. */
-interface AgentAuthScriptGrant {
-    /** Contract name, or `"*"`. */
-    scriptName: string;
-    /** Optional semver requirement; `null` to match any version. */
-    versionReq?: string | null;
-    /** Functions the agent may invoke on this contract. */
-    functions: string[];
-    /** Org-data scopes delegated to the agent for the contract functions to
-     *  read on its behalf. */
-    scopes?: string[];
-    /** Direct-read scopes the agent may enumerate itself, via whichever read
-     *  function the contract exposes for direct enumeration. A strict subset of
-     *  `scopes` (enforced contract-side). */
-    readScopes?: string[];
-    /** Optional validity-window start (unix seconds). */
-    validFromSecs?: number | null;
-    /** NEW: optional validity-window end (unix seconds). */
-    validUntilSecs?: number | null;
-    /** Egress hosts the agent may reach for this contract. */
-    allowedHosts: string[];
-}
-/** One agent's entry in the write-request shape. */
-interface AgentAuthEntry {
-    agentDid: string;
-    scripts: AgentAuthScriptGrant[];
+declare class UserUpsertError extends T3nError {
+    readonly kind: UserUpsertErrorKind | "Unknown";
+    readonly detail: string;
+    constructor(code: string, detail: string);
+    /**
+     * Try to parse a contract error string into a `UserUpsertError`.
+     * Returns `null` if `raw` doesn't match the `<code>:<detail>`
+     * shape — caller falls back to a generic error.
+     */
+    static fromWire(raw: string): UserUpsertError | null;
 }
+
 /**
- * The full agent-auth policy document in the camelCase write shape:
- * the per-agent grants plus the document-level discovery grants.
+ * Token-metering wire shapes.
  *
- * `discoverDids` (contract wire: `discover_dids`) is the
- * list of DIDs the user lets their registered agents *enumerate the
- * contracts of* via `listContracts`: an org DID grants org-mode discovery,
- * the user's own DID grants self-mode discovery. It lives at document
- * level — not on a script grant — because discovery must surface contracts
- * the agent cannot yet call. The node's discovery gate additionally
- * requires the calling agent to be named in `agents` (subject binding), so
- * an unregistered agent discovers nothing regardless of this list.
+ * Mirrors the token-metering wire contract. `u128` fields land on the
+ * wire as JSON numbers (same convention as the existing
+ * `token.get-balance` response) — JS clients with histories that
+ * exceed 2⁵³ tokens should switch to a streaming JSON parser; the
+ * common case fits in `number` losslessly.
  */
-interface AgentAuthPolicy {
-    agents: AgentAuthEntry[];
-    discoverDids: string[];
-}
 /**
- * Parse a full `agent-auth-get` response (the stored snake_case policy
- * document) into the camelCase write shape, including the document-level
- * `discover_dids`. A `null` / absent response is the empty policy.
+ * The token `BalanceRow` wire shape — caller's credit row.
+ *
+ * `available` and `reserved` are `u128` on the server; the wire
+ * format is a JSON number. Callers should not assume bigint until
+ * the SDK migrates to a streaming parser (tracked separately).
+ *
+ * ⚠️ Amounts are in **base units** (`1 token = `
+ * {@link BASE_UNITS_PER_TOKEN}), not whole tokens. Use
+ * {@link formatTokens} to display them.
  */
-declare function parseAgentAuthPolicy(response: unknown): AgentAuthPolicy;
-/** Extract the `agents` array from an `agent-auth-get` response. */
-declare function parseAgentAuthGet(response: unknown): AgentAuthEntry[];
-interface AgentAuthMergeResult {
-    /** Full merged `agents` list, ready for `agent-auth-update`. */
-    agents: AgentAuthEntry[];
-    /** `"<agentDid> → <scriptName>"` rows preserved from the existing policy. */
-    preservedRows: string[];
-}
-/** Input to the full-document write {@link T3nClient.agentAuthUpdate}. The
- *  document IS the new state: an empty `agents` list revokes all agent
- *  access, and an omitted / empty `discoverDids` persists an empty
- *  discovery-grant list (the contract has no per-field merge). Mirrors the
- *  contract `AgentAuthPolicy`. */
-interface AgentAuthUpdateInput {
-    agents: AgentAuthEntry[];
-    /** Document-level discovery grants — see {@link AgentAuthPolicy}. */
-    discoverDids?: string[];
+interface BalanceRow {
+    /** Spendable balance, in base units (see {@link formatTokens}). */
+    available: number;
+    /** Reserved balance, in base units. */
+    reserved: number;
+    last_settled_seq_no: number;
+    version: number;
+    credit_exhausted: boolean;
 }
 /**
- * Serialise a camelCase policy document to the contract's canonical
- * snake_case `agent-auth-update` wire (`agent_did` / `script_name` /
- * `version_req` / `read_scopes` / `valid_from_secs` / `valid_until_secs` /
- * `allowed_hosts` / `discover_dids`), so neither write path relies on the
- * contract's compatibility aliases. Absent optionals are omitted (never
- * sent as `null`); empty `scopes` / `read_scopes` are omitted (the
- * contract defaults both to empty). `functions` and `allowed_hosts` are
- * always emitted — the contract requires explicit functions (`["*"]` =
- * all) and reads an absent `allowed_hosts` as deny-all egress. The
- * document-level `discover_dids` (strictly snake_case — the contract
- * defines no camelCase alias for it) is emitted only when non-empty; the
- * contract defaults an absent list to empty.
+ * The token-tx-kind wire alphabet (snake_case). Every
+ * value listed here is accepted by the server-side
+ * `token.get-usage` `kinds` filter.
  */
-declare function toAgentAuthUpdateWire(agents: AgentAuthEntry[], discoverDids?: string[]): {
-    agents: Array<{
-        agent_did: string;
-        scripts: Array<Record<string, unknown>>;
-    }>;
-    discover_dids?: string[];
-};
+type TokenTxKind = "mint" | "burn" | "charge" | "transfer" | "bridge_mint_attest" | "bridge_burn_attest";
 /**
- * Order-preserving deduplicating union of discovery-grant DID lists —
- * the read-merge-write counterpart of {@link mergeAgentAuthEntries} for
- * the document-level `discoverDids` (the contract rejects duplicate
- * entries, so the union must dedupe).
+ * Per-caller view direction. `"in"` = caller's balance went up;
+ * `"out"` = caller's balance went down. Derived host-side from
+ * `(caller_did, tx.src, tx.dst)`; the same `seq_no` appears in both
+ * parties' usage feeds with opposite directions on a transfer.
  */
-declare function mergeDiscoverDids(existing: string[], additions: string[]): string[];
+type Direction = "in" | "out";
 /**
- * Merge new agent entries into the existing policy with script-level union
- * semantics: for an agent DID present on both sides, script rows whose
- * `scriptName` is not being written are preserved; rows with a matching
- * `scriptName` are replaced by the new grant. Entries for other agent DIDs
- * pass through unchanged.
+ * Discriminated union mirroring the charge-reason wire union.
+ * Present only when the row's `kind === "charge"`.
  */
-declare function mergeAgentAuthEntries(existing: AgentAuthEntry[], newEntries: AgentAuthEntry[]): AgentAuthMergeResult;
-
+type ChargeReason = {
+    kind: "contract_register";
+    script_name: string;
+    version: string;
+} | {
+    kind: "invocation";
+    script_name: string;
+    function: string;
+    fuel_consumed: number;
+    fuel_tokens: number;
+    host_call_count: number;
+    host_call_tokens: number;
+} | {
+    kind: "kv_bytes";
+    map: string;
+} | {
+    kind: "cas_bytes";
+    backend: string;
+} | {
+    kind: "outbox_egress";
+    upstream: string;
+};
 /**
- * KYC types for the `tee:user/contracts::kyc-status` short-poll
- * function.
- *
- * The shape mirrors the `kyc-status` wire response.
- * The bytes go straight from the contract
- * through the JSON-RPC envelope into [[T3nClient.kycStatus]].
+ * One row in the caller's usage feed — a per-caller projection of
+ * the underlying `TokenTx`. `counterparty` is the other party from
+ * the caller's perspective: `tx.dst` on outbound entries, `tx.src`
+ * on inbound. `null` when the underlying tx has no counterparty
+ * (mints have no `src`; burns and charges have no `dst`).
  */
-
+interface UsageEntry {
+    seq_no: number;
+    kind: TokenTxKind;
+    /** Amount moved, in base units (`1 token = `{@link BASE_UNITS_PER_TOKEN}); see {@link formatTokens}. */
+    amount: number;
+    timestamp_ms: number;
+    direction: Direction;
+    counterparty?: string | null;
+    reason?: ChargeReason | null;
+    note?: string | null;
+}
 /**
- * Terminal status for a Level 2 KYC verification, plus `pending`.
+ * Response shape of `token.get-usage` — caller's balance plus a
+ * paginated slice of their most-recent `token:tx_log` entries.
  *
- * - `pending` — provider has not delivered a verdict yet, or the
- *   webhook arrived but the post-action VC issuance hasn't completed.
- * - `verified` — provider approved AND a VC has been issued. `vcIds`
- *   carries the issued credential ids.
- * - `rejected` — provider declined / required resubmission /
- *   expired / the user abandoned the flow. `error` may carry a
- *   provider-supplied reason.
- * - `orphan` — a Veriff webhook arrived with a `vendorData` that
- *   couldn't be matched to any user. Should not
- *   happen in the MetaMask flow but the contract surfaces it for
- *   completeness.
+ * `next_cursor` is the inclusive upper-bound `seq_no` to pass back
+ * as `after_seq` to fetch the next page. `null` (or absent) means
+ * the caller's history is fully drained.
  */
-type KycStatusKind = "pending" | "verified" | "rejected" | "orphan";
+interface UsagePage {
+    balance: BalanceRow;
+    entries: UsageEntry[];
+    next_cursor?: number | null;
+}
 /**
- * Snapshot returned by `tee:user/contracts::kyc-status`.
- *
- * Field names use camelCase on the SDK boundary even though the
- * wire is snake_case — the wrapper rewrites keys at the client edge
- * so callers don't see the JSON shape leaking through.
+ * Request shape — all fields optional. `limit` clamps to
+ * `1..=200` server-side; out-of-range values snap silently to the
+ * bounds. `kinds: []` is treated as "no filter".
  */
-interface KycStatus {
-    /** Terminal status if reached, otherwise `pending`. */
-    status: KycStatusKind;
-    /**
-     * Provider being polled. Echoed back so callers that didn't
-     * supply one see the contract's default (`"veriff"` in phase one).
-     */
-    provider: string;
-    /**
-     * Unix-millis of the latest contract-visible event:
-     * VC issuance time, attestation arrival time, session-row
-     * `started_at_ms`, or orphan-record arrival time. Best-effort —
-     * `undefined` when no source carries a usable timestamp.
-     */
-    updatedAt?: number;
-    /**
-     * VC ids appended for this provider, in append order. Empty for
-     * `pending` / `rejected` / `orphan`.
-     */
-    vcIds: string[];
-    /**
-     * Provider-supplied reason for `rejected`, when available.
-     */
-    error?: string;
+interface GetUsageOptions {
+    limit?: number;
+    after_seq?: number;
+    kinds?: TokenTxKind[];
 }
+
 /**
- * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults:
- * poll fast for the first 30 seconds, then back
- * off, and bail after 5 minutes.
+ * Tenant audit-event wire shapes.
+ *
+ * Mirrors `tenant_types::AuditEvent` and the `audit.get-mine` response
+ * (`service::tenant_logs::{AuditBatch, AuditPage}`). A tenant contract
+ * emits an audit event via the `logging::audit` host call; the host
+ * stamps the identity fields (`subject` / `actor` / `vc_id`) from the
+ * verified dispatch context, so a contract can never forge who acted or
+ * on whom. Events are permanent (encrypted, append-only) and scoped to a
+ * user — distinct from the evicting debug ring read via `getContractLogs`.
  */
-interface KycPollCadence {
-    /** Poll interval in ms while `elapsed < switchAtMs`. Default: 2000. */
-    fastMs: number;
-    /** Poll interval in ms once `elapsed >= switchAtMs`. Default: 5000. */
-    slowMs: number;
-    /** Elapsed-ms threshold to switch from fast to slow cadence. Default: 30_000. */
-    switchAtMs: number;
-    /**
-     * Maximum total time to spend polling before rejecting with
-     * [[KycStatusTimeoutError]]. Default: 300_000 (5 minutes).
-     */
-    timeoutMs: number;
+/**
+ * One host-stamped audit event. `subject` / `actor` are canonical DID
+ * strings. On a self-call `actor === subject` and `vc_id` is `null`; on a
+ * delegated call `actor` is the agent and `vc_id` is the delegation
+ * credential. The remaining fields are supplied verbatim by the contract.
+ */
+interface AuditEvent {
+    /** Cluster-deterministic flush timestamp (ms). */
+    ts_ms: number;
+    /** The user whose data the call touched (host-stamped `pii_did`). */
+    subject: string;
+    /** The agent (delegated) or user (self-call) who acted (host-stamped). */
+    actor: string;
+    /** Delegation credential id on a delegated call; `null` on a self-call. */
+    vc_id?: string | null;
+    /** Contract-supplied: what happened, e.g. `"kyc.approve"`. */
+    action: string;
+    /** Contract-supplied: what it acted on, e.g. `"user-profile"`. */
+    target: string;
+    /** Contract-supplied: the result, e.g. `"success"` / `"denied"`. */
+    outcome: string;
+    /** Contract-supplied: optional free-text / JSON detail. */
+    details?: string | null;
 }
 /**
- * Optional knobs for [[T3nClient.kycStatusPoll]]. Most callers won't
- * touch any of these — the cadence defaults are baked in.
+ * One archived batch — the events committed in a single tenant dispatch.
+ * Every event in a batch shares the same `subject` / `actor` / `vc_id`.
  */
-interface KycPollOptions {
-    /**
-     * Cancellation signal. When aborted, the helper rejects with
-     * `signal.reason` (or a generic `AbortError` if the consumer
-     * didn't supply a reason). The currently-in-flight `kycStatus()`
-     * call also receives the signal so it can short-circuit.
-     */
-    signal?: AbortSignal;
-    /**
-     * Called with every snapshot the helper receives, including
-     * non-terminal `pending` ones. Useful for surfacing intermediate
-     * UI states (e.g. "still waiting on provider…"). Errors thrown
-     * from this callback are caught and ignored — they must not
-     * sink the poll loop.
-     */
-    onUpdate?: (status: KycStatus) => void;
-    /**
-     * Override one or more cadence fields. Anything not specified
-     * uses the defaults from [[DEFAULT_KYC_POLL_CADENCE]].
-     */
-    cadence?: Partial<KycPollCadence>;
+interface AuditBatch {
+    /** Hex of the archive key — usable directly as `cursor` for the next page. */
+    key: string;
     /**
-     * Provider id to poll. Defaults to the contract default
-     * (`"veriff"` in phase one). Mirrored on the wire as
-     * `input.provider_id`.
+     * Host-stamped: did the emitting dispatch's contract transaction
+     * commit? `false` means the call rolled back or trapped, so an event's
+     * `outcome: "success"` in this batch is the contract's *claim*, not a
+     * committed fact — filter on this when you need only durable events.
      */
-    providerId?: string;
+    committed: boolean;
+    events: AuditEvent[];
 }
 /**
- * Default cadence used by [[T3nClient.kycStatusPoll]] when the caller
- * doesn't override `cadence.*`.
- */
-declare const DEFAULT_KYC_POLL_CADENCE: KycPollCadence;
-/**
- * Subset of [[KycStatusKind]] that ends a poll. `pending` is the
- * only non-terminal value.
+ * `audit.get-mine` response — a page of audit batches, newest scan order.
+ * `next_cursor` is present (a key hex) when more batches remain; `null`
+ * once the scan reaches the end.
  */
-declare const TERMINAL_KYC_STATUSES: ReadonlySet<KycStatusKind>;
+interface AuditPage {
+    batches: AuditBatch[];
+    next_cursor?: string | null;
+}
 /**
- * Thrown by [[T3nClient.kycStatusPoll]] when the cadence's
- * `timeoutMs` elapses without a terminal status arriving. The
- * `lastStatus` field is the most recent (necessarily `pending`)
- * snapshot the helper saw, useful for surfacing "we tried for N
- * minutes but Veriff is still working" UX.
+ * Request shape for {@link T3nClient.getAuditEvents} — all fields
+ * optional. Omit `pii_did` to read your own trail (all actors); set it to
+ * another user's DID to read, as a delegated agent, the events you
+ * performed for them — admitted only while that user's agent-auth grant
+ * to you is live. `cursor` is the `next_cursor` from a prior page.
  */
-declare class KycStatusTimeoutError extends T3nError {
-    /** The timeout (ms) the helper exhausted before a terminal status arrived. */
-    readonly timeoutMs: number;
-    /** The last `pending` snapshot before timeout, if any. */
-    readonly lastStatus?: KycStatus | undefined;
-    constructor(
-    /** The timeout (ms) the helper exhausted before a terminal status arrived. */
-    timeoutMs: number, 
-    /** The last `pending` snapshot before timeout, if any. */
-    lastStatus?: KycStatus | undefined);
+interface GetAuditEventsOptions {
+    pii_did?: string;
+    limit?: number;
+    cursor?: string;
 }
 
 /**
@@ -2755,70 +2582,216 @@ declare function createRandomHandler(): GuestToHostHandler;
 declare function createDefaultHandlers(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandlers;
 
 /**
- * Payroll request shapes + shared encoding utilities.
+ * Token fixed-point units (USDT-style 6 decimals).
  *
- * Envelope-free authorisation removed the per-call delegation
- * credential and envelope entirely: authority is now the standing on-chain
- * `agent_auth` ∩ `UserGrant` intersection the host re-reads every call, and
- * every payroll call emits the plain Direct wire variant (`{ request }`).
- * What remains here is the request body shape, its canonical defaults, and
- * the base64url / DID helpers callers still need.
+ * As of `tee:*` metering v2, every token amount on the wire —
+ * {@link BalanceRow}'s `available`/`reserved`, {@link UsageEntry.amount},
+ * and `total_supply` — is denominated in **base units**, where
+ * `1 T3N token = `{@link BASE_UNITS_PER_TOKEN}` base units`. The node
+ * meters the *actual* fractional cost of each operation (pro-rata by
+ * bytes / byte-seconds / fuel) down to `1e-6` token, so amounts are
+ * raw integers in base units, NOT whole tokens.
  *
- * Wire conventions retained from the contract:
- *   - `batch_cap_cents` is emitted as a **JSON string** so JS Number
- *     precision never enters the wire surface.
- *   - binary fields are base64url-no-pad strings.
- *   - `org_id` is `did:t3n:<40-hex>` (the `CompactDid` `Display` form).
+ * The wire fields are left as raw base units (no silent rescaling — that
+ * would lose precision for large balances and surprise callers doing
+ * arithmetic). Use {@link formatTokens} to render a human "tokens"
+ * string and {@link toBaseUnits} to convert a token figure back.
+ *
+ * ⚠️ Breaking vs. the pre-decimals SDK: a balance that used to read `5`
+ * (whole tokens) now reads `5_000_000` (base units). Multiply existing
+ * display code through {@link formatTokens}.
  */
+/** Decimal places in a T3N token (fixed; mirrors the node constant). */
+declare const TOKEN_DECIMALS = 6;
+/** Base units per whole T3N token — `10 ** TOKEN_DECIMALS`. */
+declare const BASE_UNITS_PER_TOKEN = 1000000;
 /**
- * Canonical sorted run-pipeline function surface for the z-payroll contract
- * (`z:<org-tid>:payroll`). Sorted ascending. Mirrors `Z_PAYROLL_RUN_FUNCTIONS`
- * in the Trinity harness; used as the `functions` set for agent-auth grants
- * and `check-delegation` queries.
+ * Render a base-unit amount as a human-readable token string, e.g.
+ * `25_920_000 → "25.92"`, `1_000_000 → "1"`, `4768 → "0.004768"`.
+ *
+ * Trailing-zero fraction digits are trimmed; an integer amount renders
+ * with no decimal point. Accepts `number` or `bigint`; for balances
+ * above `Number.MAX_SAFE_INTEGER` prefer passing a `bigint`.
  */
-declare const Z_PAYROLL_RUN_FUNCTIONS: readonly ["compute-payroll", "execute-disbursement", "finalize-audit", "submit-escalations", "validate-credentials"];
+declare function formatTokens(baseUnits: number | bigint): string;
 /**
- * Canonical sorted audit-read function surface for the z-payroll contract.
- * These functions authorise history reads via `list-audit-cycles` /
- * `get-audit-entry`.
+ * Convert a whole-or-fractional token figure to base units (rounded to
+ * the nearest base unit). E.g. `25.92 → 25_920_000`, `1 → 1_000_000`.
+ */
+declare function toBaseUnits(tokens: number): number;
+
+/**
+ * Org-data wire types mirroring the org-data contract wire shapes.
+ *
+ * Plain TypeScript interfaces (no zod) — the SDK does not use a
+ * validation library for domain types; see the existing `types/` files.
+ *
+ * Each response type below is paired with a shallow runtime predicate
+ * (`isMutationResponse`, `isOrgPolicyMeta`, etc.) so the org-data client
+ * can `assertShape` the decoded payload before returning to callers.
+ * Predicates check the top-level structure only; nested elements
+ * (e.g. each `UserGrant` inside `OrgContractGrants.grants`) are not
+ * deeply validated — see `utils/shape.ts` for the rationale.
+ *
+ * Reference: the org-data wire contract.
+ */
+/**
+ * Capability grant stored under `ORG_CONTRACT_GRANTS_MAP`.
+ *
+ * Mirrors the org-data `UserGrant` wire shape.
+ */
+interface UserGrant {
+    /** The user this grant applies to (`did:t3n:<40-hex>`). */
+    user_did: string;
+    /** WIT function names the user may invoke (e.g. `"set-records"`). */
+    functions: string[];
+    /** Data scope paths the user may access (e.g. `"example/records"`). */
+    scopes: string[];
+    /**
+     * Optional key-value constraints that must match the request metadata
+     * exactly for every key present in this map.
+     */
+    constraints: Record<string, string>;
+    /** Unix timestamp (secs) after which this grant is expired. `null` means never expires. */
+    expires_at_secs: number | null;
+}
+/**
+ * Policy record for an organisation's data tier.
+ *
+ * Mirrors the org-data policy-meta wire shape.
+ */
+interface OrgPolicyMeta {
+    /** DIDs (`did:t3n:<40-hex>`) of users authorised to manage policy and read data. */
+    admins: string[];
+    /** Maximum number of admins allowed for this org. */
+    max_admins: number;
+    /** Unix timestamp (secs) when the policy was first created. */
+    created_at_secs: number;
+    /** Unix timestamp (secs) of the most recent policy update. */
+    updated_at_secs: number;
+    /**
+     * Per-org ceiling on delegation-credential validity (seconds).
+     *
+     * Absent when no org-level cap is set — the contract omits the field
+     * (never serialises null) and the cluster-wide
+     * `delegation.max_credential_validity_secs` governs instead. When set,
+     * the effective cap is `min(max_credential_validity_secs, cluster_ceiling)`.
+     */
+    max_credential_validity_secs?: number;
+}
+/** Shallow runtime guard for {@link OrgPolicyMeta}. */
+declare function isOrgPolicyMeta(value: unknown): value is OrgPolicyMeta;
+/**
+ * Effective org policy view returned by `org-policy-view`.
+ *
+ * Readable by any authenticated session (non-sensitive metadata).
+ * Returns the **effective** credential validity cap:
+ * `min(org.max_credential_validity_secs, cluster_ceiling)`, equal to the
+ * cluster ceiling when the org has not set a per-org cap. The contract
+ * always returns a value (or errors) — the field is never null.
+ */
+interface OrgPolicyView {
+    /**
+     * Effective delegation-credential validity cap in seconds:
+     * `min(org value, cluster ceiling)`, equal to the cluster ceiling when the
+     * org has not set a per-org cap. Always present — mirrors the contract's
+     * `PolicyViewResponse.effective_validity_secs` (org-data `org-policy-view`).
+     */
+    effective_validity_secs: number;
+}
+/** Shallow runtime guard for {@link OrgPolicyView}. */
+declare function isOrgPolicyView(value: unknown): value is OrgPolicyView;
+/**
+ * Standard response returned by all policy write and data mutation operations.
+ *
+ * Mirrors the org-data `MutationResponse` wire shape.
+ */
+interface MutationResponse {
+    /** `"created"`, `"updated"`, or `"deleted"`. */
+    status: string;
+    /** Hex-encoded entry ID; present on data write/delete operations. */
+    entry_id?: string;
+    /** Whether the target key existed before deletion; present on single-entry deletes. */
+    deleted?: boolean;
+    /** Number of entries removed; present on `org-data-delete-scope`. */
+    deleted_entries?: number;
+    tx_hash: string | null;
+}
+/**
+ * Shallow runtime guard for {@link MutationResponse}.
+ *
+ * Only the always-present fields are checked — `status` is mandatory on
+ * every mutation; `tx_hash` is non-optional but nullable. The optional
+ * fields (`entry_id`, `deleted`, `deleted_entries`) are not validated
+ * because their presence depends on which mutation ran.
+ */
+declare function isMutationResponse(value: unknown): value is MutationResponse;
+/**
+ * Response type alias for org-writers-get.
+ *
+ * The wire body is `{ writers: string[] }` where each entry is
+ * `did:t3n:<40-hex>`.
+ */
+interface OrgWriters {
+    writers: string[];
+}
+/** Shallow runtime guard for {@link OrgWriters}. */
+declare function isOrgWriters(value: unknown): value is OrgWriters;
+/**
+ * Response type alias for org-grants-get.
+ *
+ * The wire body echoes the `contract_id` alongside the grant list.
  */
-declare const Z_PAYROLL_AUDIT_READ_FUNCTIONS: readonly ["get-audit-entry", "list-audit-cycles"];
-/** Payroll-specific request body — the Direct wire variant carries `{ request }`. */
-interface PayrollRunRequest {
-    /** `did:t3n:<40-hex>` org id. */
-    org_id: string;
-    cycle_id: string;
-    pay_period_start: string;
-    pay_period_end: string;
-    /** Total cap on the run's net disbursement, in cents. */
-    batch_cap_cents: bigint;
-    /** `employee_id` → previous-cycle baseline net disbursement, cents (decimal string). */
-    historical_baselines: Record<string, string>;
-    /**
-     * Per-employee disbursement flag threshold, in cents. When absent the
-     * contract applies its own default (SGD 15,000); when present it is included
-     * in the wire shape.
-     */
-    individual_disbursement_threshold_cents?: bigint;
+interface OrgContractGrants {
+    contract_id: string;
+    grants: UserGrant[];
 }
-/** Default for `individual_disbursement_threshold_cents` — SGD 15,000. */
-declare const DEFAULT_INDIVIDUAL_THRESHOLD_CENTS = 1500000n;
-declare function b64uEncode(input: Uint8Array): string;
 /**
- * Encode raw bytes to base64url-no-pad (RFC 4648 §5 with padding dropped).
- * The encoding the wire uses for binary fields.
+ * Shallow runtime guard for {@link OrgContractGrants}.
+ *
+ * Validates the immediate envelope (`contract_id: string`, `grants:
+ * array`) without recursing into each `UserGrant`. The Rust contract
+ * is the source of truth for grant element shape; widening the predicate
+ * here would create maintenance churn against benign field additions.
  */
-declare function b64uEncodeBytes(input: Uint8Array): string;
+declare function isOrgContractGrants(value: unknown): value is OrgContractGrants;
+/** Response for `org-data-list`. */
+interface DataListResponse {
+    /** Hex-encoded entry IDs for this page. */
+    entry_ids: string[];
+    /** Offset to pass for the next page. `null` when this is the last page. */
+    next_offset: number | null;
+    /** Total number of entries in the scope (across all pages). */
+    total: number;
+}
+/** Shallow runtime guard for {@link DataListResponse}. */
+declare function isDataListResponse(value: unknown): value is DataListResponse;
+/** Response for `org-data-get`. */
+interface DataGetResponse {
+    entry_id: string;
+    /** Hex-encoded raw payload bytes. */
+    payload_hex: string;
+}
+/** Shallow runtime guard for {@link DataGetResponse}. */
+declare function isDataGetResponse(value: unknown): value is DataGetResponse;
 /**
- * Decode a base64url-no-pad string. Strict — rejects standard-alphabet
- * `+` / `/` and any padding `=`.
+ * Legacy direct-route org-data envelope shape retained for compatibility.
+ *
+ * This mirrors the removed `/api/user-contract/execute` body format from
+ * the transitional transport. New callers should use `OrgDataClient`,
+ * which now dispatches through authenticated `/api/rpc` +
+ * `action.execute` instead.
  */
-declare function b64uDecodeStrict(input: string): Uint8Array;
-/** @internal — preserved alias for in-tree callers. Prefer
- *  {@link b64uEncodeBytes} / {@link b64uDecodeStrict}. */
-declare const _b64uEncode: typeof b64uEncode;
-/** Build a `did:t3n:<40-hex>` from raw 20 bytes. */
-declare function compactDidFromBytes(bytes: Uint8Array): string;
+interface OrgDataActionWire {
+    nonce: string;
+    user_did: string;
+    authenticator_id: string;
+    contract_id: string;
+    function: string;
+    args_hash: string;
+    expires_at_secs: number;
+    signature: string;
+}
 
 /**
  * OrgDataClient — typed wrapper over the existing authenticated
@@ -3167,43 +3140,110 @@ declare class SessionOrgDataClient {
 declare function createOrgDataClientFromSession(t3n: T3nClient, baseUrl: string): SessionOrgDataClient;
 
 /**
- * Token fixed-point units (USDT-style 6 decimals).
- *
- * As of `tee:*` metering v2, every token amount on the wire —
- * {@link BalanceRow}'s `available`/`reserved`, {@link UsageEntry.amount},
- * and `total_supply` — is denominated in **base units**, where
- * `1 T3N token = `{@link BASE_UNITS_PER_TOKEN}` base units`. The node
- * meters the *actual* fractional cost of each operation (pro-rata by
- * bytes / byte-seconds / fuel) down to `1e-6` token, so amounts are
- * raw integers in base units, NOT whole tokens.
+ * Payroll request shapes + shared encoding utilities.
  *
- * The wire fields are left as raw base units (no silent rescaling — that
- * would lose precision for large balances and surprise callers doing
- * arithmetic). Use {@link formatTokens} to render a human "tokens"
- * string and {@link toBaseUnits} to convert a token figure back.
+ * Envelope-free authorisation removed the per-call delegation
+ * credential and envelope entirely: authority is now the standing on-chain
+ * `agent_auth` ∩ `UserGrant` intersection the host re-reads every call, and
+ * every payroll call emits the plain Direct wire variant (`{ request }`).
+ * What remains here is the request body shape, its canonical defaults, and
+ * the base64url / DID helpers callers still need.
  *
- * ⚠️ Breaking vs. the pre-decimals SDK: a balance that used to read `5`
- * (whole tokens) now reads `5_000_000` (base units). Multiply existing
- * display code through {@link formatTokens}.
+ * Wire conventions retained from the contract:
+ *   - `batch_cap_cents` is emitted as a **JSON string** so JS Number
+ *     precision never enters the wire surface.
+ *   - binary fields are base64url-no-pad strings.
+ *   - `org_id` is `did:t3n:<40-hex>` (the `CompactDid` `Display` form).
  */
-/** Decimal places in a T3N token (fixed; mirrors the node constant). */
-declare const TOKEN_DECIMALS = 6;
-/** Base units per whole T3N token — `10 ** TOKEN_DECIMALS`. */
-declare const BASE_UNITS_PER_TOKEN = 1000000;
 /**
- * Render a base-unit amount as a human-readable token string, e.g.
- * `25_920_000 → "25.92"`, `1_000_000 → "1"`, `4768 → "0.004768"`.
- *
- * Trailing-zero fraction digits are trimmed; an integer amount renders
- * with no decimal point. Accepts `number` or `bigint`; for balances
- * above `Number.MAX_SAFE_INTEGER` prefer passing a `bigint`.
+ * Canonical sorted run-pipeline function surface for the z-payroll contract
+ * (`z:<org-tid>:payroll`). Sorted ascending. Mirrors `Z_PAYROLL_RUN_FUNCTIONS`
+ * in the Trinity harness; used as the `functions` set for agent-auth grants
+ * and `check-delegation` queries.
  */
-declare function formatTokens(baseUnits: number | bigint): string;
+declare const Z_PAYROLL_RUN_FUNCTIONS: readonly ["compute-payroll", "execute-disbursement", "finalize-audit", "submit-escalations", "validate-credentials"];
 /**
- * Convert a whole-or-fractional token figure to base units (rounded to
- * the nearest base unit). E.g. `25.92 → 25_920_000`, `1 → 1_000_000`.
+ * Canonical sorted audit-read function surface for the z-payroll contract.
+ * These functions authorise history reads via `list-audit-cycles` /
+ * `get-audit-entry`.
  */
-declare function toBaseUnits(tokens: number): number;
+declare const Z_PAYROLL_AUDIT_READ_FUNCTIONS: readonly ["get-audit-entry", "list-audit-cycles"];
+/** Payroll-specific request body — the Direct wire variant carries `{ request }`. */
+interface PayrollRunRequest {
+    /** `did:t3n:<40-hex>` org id. */
+    org_id: string;
+    cycle_id: string;
+    pay_period_start: string;
+    pay_period_end: string;
+    /** Total cap on the run's net disbursement, in cents. */
+    batch_cap_cents: bigint;
+    /** `employee_id` → previous-cycle baseline net disbursement, cents (decimal string). */
+    historical_baselines: Record<string, string>;
+    /**
+     * Per-employee disbursement flag threshold, in cents. When absent the
+     * contract applies its own default (SGD 15,000); when present it is included
+     * in the wire shape.
+     */
+    individual_disbursement_threshold_cents?: bigint;
+}
+/** Default for `individual_disbursement_threshold_cents` — SGD 15,000. */
+declare const DEFAULT_INDIVIDUAL_THRESHOLD_CENTS = 1500000n;
+declare function b64uEncode(input: Uint8Array): string;
+/**
+ * Encode raw bytes to base64url-no-pad (RFC 4648 §5 with padding dropped).
+ * The encoding the wire uses for binary fields.
+ */
+declare function b64uEncodeBytes(input: Uint8Array): string;
+/**
+ * Decode a base64url-no-pad string. Strict — rejects standard-alphabet
+ * `+` / `/` and any padding `=`.
+ */
+declare function b64uDecodeStrict(input: string): Uint8Array;
+/** @internal — preserved alias for in-tree callers. Prefer
+ *  {@link b64uEncodeBytes} / {@link b64uDecodeStrict}. */
+declare const _b64uEncode: typeof b64uEncode;
+/** Build a `did:t3n:<40-hex>` from raw 20 bytes. */
+declare function compactDidFromBytes(bytes: Uint8Array): string;
+
+/** Closed-vocabulary serialisation annotations for a contract function's body. */
+interface WireBlock {
+    /**
+     * Field paths whose values are emitted as decimal strings. A path ending in
+     * `.*` applies to every value of the named object/array (e.g.
+     * `historical_baselines.*`).
+     */
+    u64_as_string?: string[];
+    /**
+     * Byte fields carried as typed strings. The value is passed through when it
+     * is already a string; a byte input (`Uint8Array` or a `number[]` of octets)
+     * is encoded per its kind.
+     */
+    string_encoded?: Record<string, StringEncoding>;
+}
+/** The closed set of `string_encoded` field kinds. */
+type StringEncoding = "did" | "address" | "hash";
+/**
+ * Raised when a `wire` block asks for a projection the closed vocabulary cannot
+ * express — an unrepresentable value for a declared field. It signals a
+ * descriptor↔contract mismatch on the author's side, so callers surface it as a
+ * terminal `unsupported_wire_encoding` rather than retrying.
+ */
+declare class WireEncodingError extends T3nError {
+    readonly field: string;
+    readonly encoding?: StringEncoding | undefined;
+    constructor(message: string, field: string, encoding?: StringEncoding | undefined);
+}
+type JsonRecord = Record<string, unknown>;
+/**
+ * Project `args` into the plain-args body a z-space contract deserialises,
+ * applying the descriptor's `wire` annotations. Returns a new object; `args` is
+ * never mutated. With no `wire` block the body is returned unchanged (the
+ * JSON-plain path).
+ *
+ * @throws {WireEncodingError} when a declared field holds a value the
+ *   vocabulary cannot express.
+ */
+declare function requestToWire(args: JsonRecord, wire?: WireBlock): JsonRecord;
 
 /**
  * SessionUsageReportClient — typed wrapper over the authenticated
@@ -3291,46 +3331,6 @@ declare class SessionUsageReportClient {
  */
 declare function createUsageReportClientFromSession(t3n: T3nClient, baseUrl: string): SessionUsageReportClient;
 
-/** Closed-vocabulary serialisation annotations for a contract function's body. */
-interface WireBlock {
-    /**
-     * Field paths whose values are emitted as decimal strings. A path ending in
-     * `.*` applies to every value of the named object/array (e.g.
-     * `historical_baselines.*`).
-     */
-    u64_as_string?: string[];
-    /**
-     * Byte fields carried as typed strings. The value is passed through when it
-     * is already a string; a byte input (`Uint8Array` or a `number[]` of octets)
-     * is encoded per its kind.
-     */
-    string_encoded?: Record<string, StringEncoding>;
-}
-/** The closed set of `string_encoded` field kinds. */
-type StringEncoding = "did" | "address" | "hash";
-/**
- * Raised when a `wire` block asks for a projection the closed vocabulary cannot
- * express — an unrepresentable value for a declared field. It signals a
- * descriptor↔contract mismatch on the author's side, so callers surface it as a
- * terminal `unsupported_wire_encoding` rather than retrying.
- */
-declare class WireEncodingError extends T3nError {
-    readonly field: string;
-    readonly encoding?: StringEncoding | undefined;
-    constructor(message: string, field: string, encoding?: StringEncoding | undefined);
-}
-type JsonRecord = Record<string, unknown>;
-/**
- * Project `args` into the plain-args body a z-space contract deserialises,
- * applying the descriptor's `wire` annotations. Returns a new object; `args` is
- * never mutated. With no `wire` block the body is returned unchanged (the
- * JSON-plain path).
- *
- * @throws {WireEncodingError} when a declared field holds a value the
- *   vocabulary cannot express.
- */
-declare function requestToWire(args: JsonRecord, wire?: WireBlock): JsonRecord;
-
 /**
  * Cryptographic utilities for T3n SDK
  *
@@ -3717,6 +3717,18 @@ type TenantMapUpdatePatch = MapUpdateInput;
 type TenantContractPublishInput = ContractPublishInput;
 type TenantContractSetDescriptorInput = ContractSetDescriptorInput;
 type TenantContractExecuteInput = ContractExecuteInput;
+/**
+ * Coarse lifecycle state of a tenant map, mirroring the contract's
+ * `MapLifecycleStatus` enum on the `tee:tenant/contracts::map-get-status` op.
+ * Exported from the SDK public barrel so FE code has a single source of truth
+ * for the union instead of re-declaring it.
+ *
+ * - `"active"`  — a live map (`Private`/`Public`) exists at this name.
+ * - `"deleting"` — deleted, host sweeper still draining. Poll until `"absent"`.
+ * - `"absent"`  — no row (never created, or deletion fully settled); name is
+ *   free to (re-)create.
+ */
+type MapLifecycleStatus = "active" | "deleting" | "absent";
 /**
  * Options shared by the `tee:tenant` management calls that accept an optional
  * `tenant` target argument.
@@ -3769,6 +3781,45 @@ declare class TenantMapsNamespace {
     create(input: MapCreateInput, opts?: TenantTargetOptions): Promise<unknown>;
     update(tail: string, patch: MapUpdateInput, opts?: TenantTargetOptions): Promise<unknown>;
     delete(tail: string, opts?: TenantTargetOptions): Promise<unknown>;
+    /**
+     * Write a UTF-8 key/value entry into an owned map via the tenant management
+     * surface (`map-entry-set`). Mirrors the `.delete` shape: canonical name is
+     * always rooted at the target tenant, and `payload.tenant` is included only
+     * when `opts.tenantTarget` is supplied (`exactOptionalPropertyTypes` — never
+     * pass a stringified `null`, the contract's `deny_unknown_fields` accepts an
+     * absent field, not a literal `null`).
+     *
+     * SDK-only addition: the `map-entry-set` contract op
+     * has always accepted the optional `tenant` field and routed through
+     * `resolve_tenant_did` — this helper simply completes the SDK's map-entry
+     * surface so `set` / `get` / `getStatus` are all first-class alongside the
+     * lifecycle trio.
+     */
+    entrySet(tail: string, key: string, value: string, opts?: TenantTargetOptions): Promise<void>;
+    /**
+     * Read back a UTF-8 key/value entry from an owned map via the tenant
+     * management surface (`map-entry-get`). Requires the paired contract-side
+     * 1.24.0-or-later registration for the `tenant` argument to be accepted —
+     * a node on an earlier contract rejects `tenant`-bearing requests with
+     * `deny_unknown_fields`.
+     *
+     * Unwraps the contract's `{ value: string | null }` envelope to
+     * `string | null` for caller ergonomics; `null` is the deliberate
+     * "key absent" signal, not an error.
+     */
+    entryGet(tail: string, key: string, opts?: TenantTargetOptions): Promise<string | null>;
+    /**
+     * Report the lifecycle status of an owned map (`map-get-status`),
+     * so a client can poll a delete → recreate cycle instead of guessing.
+     * Requires the paired contract-side 1.24.0-or-later registration for the
+     * `tenant` argument to be accepted.
+     *
+     * `"absent"` (never created, or deletion fully settled) is a *success*
+     * answer meaning the name is free to (re-)create; it is not an error.
+     * `"deleting"` means the host sweeper is still draining the map — poll
+     * again until `"absent"`.
+     */
+    getStatus(tail: string, opts?: TenantTargetOptions): Promise<MapLifecycleStatus>;
 }
 declare class TenantContractsNamespace {
     private readonly client;
@@ -3892,4 +3943,4 @@ declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
 export { AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MockTransport, NODE_URLS, OrgDataClient, OtpRateLimitedError, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, SessionUsageReportClient, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TOKEN_DECIMALS, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, WasmError, WireEncodingError, Z_PAYROLL_AUDIT_READ_FUNCTIONS, Z_PAYROLL_RUN_FUNCTIONS, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, bytesToString, canonicalTenantName, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isUnsafeTrustServer, loadConfig, loadWasmComponent, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyTdxQuote };
-export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export type { AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractKind, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListContractsParams, ListContractsResult, ListContractsScope, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };