@terminal3/t3n-sdk 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -434,18 +434,16 @@ declare function decodeWasmErrorMessage(errorMessage: string): string;
 declare function extractWasmError(error: unknown): string;
 
 /**
- * MAT-1374 — wire types for the explicit `otp-request` /
+ * 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 Rust types in
- * `node/tee_contracts/user/src/otp_types.rs` and
- * `node/tee_contracts/user/src/upsert_types.rs`.
+ * shapes here mirror the OTP / user-upsert wire contract.
  *
- * Keep the two in sync — bytes flow directly from the contract
+ * Bytes flow directly from the contract
  * through the JSON-RPC envelope into the SDK wrappers
  * (`T3nClient.otpRequest`, `T3nClient.otpVerify`,
  * `T3nClient.submitUserInput`).
@@ -475,8 +473,7 @@ type OtpRequestInput = {
     };
 };
 /**
- * Response returned by `otp-request`. Mirrors `OtpResponse` in
- * `otp_types.rs`.
+ * Response returned by `otp-request`. Mirrors the OTP wire response.
  *
  * - `contact` echoes the OTP destination so clients that race
  *   multiple channels can correlate replies.
@@ -520,8 +517,7 @@ interface OtpMergeSuggestion {
     channel: OtpChannel;
 }
 /**
- * Response returned by `otp-verify`. Mirrors
- * `OtpVerifyResponse` in `otp_types.rs`.
+ * 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
@@ -542,18 +538,24 @@ interface OtpVerifyResult {
     isNewProfile?: boolean;
 }
 /**
- * Level-1 user-input fields accepted by the slim `user-upsert`.
- * The Rust contract validates these via `validate_profile`; the
- * shape is intentionally open so callers can add provider-specific
- * fields on top of the canonical six.
+ * 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 {
-    firstName?: string;
-    lastName?: string;
+    first_name?: string;
+    last_name?: string;
+    country_of_residence?: string;
+    document_issuance_country?: string;
+    ssn?: string;
+    address?: string;
     email_address?: string;
     phone_number?: string;
-    birthdate?: string;
-    nationality?: string;
     campaign_code?: string;
     role?: string;
     [key: string]: unknown;
@@ -571,12 +573,12 @@ interface SubmitUserInputArgs {
     /**
      * 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 (T3-TS-026 §13).
+     * attestation if the DID has no profile yet.
      * Most callers should leave this `undefined`.
      */
     requireExistingUser?: boolean;
     /**
-     * MAT-1618 testnet self-admit. When `true`, the contract additionally
+     * 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
@@ -592,7 +594,7 @@ interface SubmitUserInputArgs {
     becomeDevTenant?: boolean;
 }
 /**
- * MAT-1618 self-admit projection from `user-upsert`. Present only
+ * Testnet self-admit projection from `user-upsert`. Present only
  * when the caller set `becomeDevTenant: true` on the request.
  *
  * - `status: "admitted"` — first call for this DID; tenant record
@@ -613,7 +615,7 @@ interface TenantAdmitProjection {
 }
 /**
  * Response shape returned by the slim `user-upsert`. Carries the
- * post-merge tx hash plus the L1 merge diagnostics
+ * post-merge tx hash plus the Level-1 merge diagnostics
  * (`refusedFields`, `mergeSuggestion`) the pre-2.0.0 omnibus
  * `UpsertResponse` already surfaced.
  */
@@ -623,16 +625,15 @@ interface SubmitUserInputResult {
     mergeSuggestion?: OtpMergeSuggestion;
     userFound?: boolean;
     /**
-     * MAT-1618 self-admit projection. Present only when the caller
+     * Testnet self-admit projection. Present only when the caller
      * set `becomeDevTenant: true` on the request.
      */
     tenantAdmit?: TenantAdmitProjection;
 }
 /**
  * Discriminator for {@link UserUpsertError}. Mirrors the
- * `UserUpsertError` Rust enum and its `<code>:<detail>` wire
- * format (see `upsert_types.rs::UserUpsertError::code`). Branch
- * with a `switch` over `kind`.
+ * `UserUpsertError` wire enum and its `<code>:<detail>` wire
+ * format. Branch with a `switch` over `kind`.
  *
  * - `EmailNotVerified` — the slim `user-upsert` was called against
  *   a DID that has no verified email and no proving authenticator.
@@ -671,8 +672,7 @@ declare class UserUpsertError extends T3nError {
 }
 
 /**
- * Org-data wire types mirroring the Rust contract shapes in
- * `tee-contract-org-data` and `org-data-types`.
+ * 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.
@@ -684,13 +684,12 @@ declare class UserUpsertError extends T3nError {
  * (e.g. each `UserGrant` inside `OrgContractGrants.grants`) are not
  * deeply validated — see `utils/shape.ts` for the rationale.
  *
- * Reference: `org-data-types/src/lib.rs` and
- * `tee-contract-org-data/src/org_data.rs`.
+ * Reference: the org-data wire contract.
  */
 /**
  * Capability grant stored under `ORG_CONTRACT_GRANTS_MAP`.
  *
- * Mirrors `org_data_types::UserGrant`.
+ * Mirrors the org-data `UserGrant` wire shape.
  */
 interface UserGrant {
     /** The user this grant applies to (`did:t3n:<40-hex>`). */
@@ -710,7 +709,7 @@ interface UserGrant {
 /**
  * Policy record for an organisation's data tier.
  *
- * Mirrors `org_data_types::OrgPolicyMeta`.
+ * Mirrors the org-data policy-meta wire shape.
  */
 interface OrgPolicyMeta {
     /** DIDs (`did:t3n:<40-hex>`) of users authorised to manage policy and read data. */
@@ -738,7 +737,7 @@ interface ExpenseClaim {
 /**
  * Employee data row stored under `OrgData[org || "payroll/employees" || entry_id]`.
  *
- * Mirrors `tee-contract-payroll::types::EmployeeRecord`.
+ * Mirrors the payroll `EmployeeRecord` wire shape.
  */
 interface EmployeeRecord {
     employee_id: string;
@@ -762,7 +761,7 @@ interface EmployeeRecord {
 /**
  * Standard response returned by all policy write and data mutation operations.
  *
- * Mirrors `tee-contract-org-data::org_data::MutationResponse`.
+ * Mirrors the org-data `MutationResponse` wire shape.
  */
 interface MutationResponse {
     /** `"created"`, `"updated"`, or `"deleted"`. */
@@ -852,16 +851,16 @@ interface OrgDataActionWire {
 }
 
 /**
- * Token-metering types — T3-TS-030 wire shapes.
+ * Token-metering wire shapes.
  *
- * Mirrors `node/primitives/src/token.rs`. `u128` fields land on the
+ * 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.
  */
 /**
- * `primitives::token::BalanceRow` — caller's credit row.
+ * 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
@@ -875,7 +874,7 @@ interface BalanceRow {
     credit_exhausted: boolean;
 }
 /**
- * `primitives::token::TokenTxKind` snake_case wire alphabet. Every
+ * The token-tx-kind wire alphabet (snake_case). Every
  * value listed here is accepted by the server-side
  * `token.get-usage` `kinds` filter.
  */
@@ -888,7 +887,7 @@ type TokenTxKind = "mint" | "burn" | "charge" | "transfer" | "bridge_mint_attest
  */
 type Direction = "in" | "out";
 /**
- * Discriminated union mirroring `primitives::token::ChargeReason`.
+ * Discriminated union mirroring the charge-reason wire union.
  * Present only when the row's `kind === "charge"`.
  */
 type ChargeReason = {
@@ -1091,7 +1090,7 @@ declare class MockTransport implements Transport {
     /**
      * 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 (MAT-983). Unset methods
+     * from the `auth.handshake` response. Unset methods
      * default to no headers.
      */
     mockResponseHeaders(method: string, headers: Record<string, string>): void;
@@ -1166,17 +1165,14 @@ interface T3nClientConfig {
  * Trinity contracts are declared as `result<list<u8>, string>` in WIT and
  * return JSON-encoded bytes. The server-side pipeline is:
  *
- * 1. `node/wasm/src/dynamic.rs:component_val_to_json` deserializes those
- *    bytes to a JSON `Value` (the contract's decoded return value).
- * 2. `node/wasm/src/runner.rs:run_dynamic` wraps that value in a
- *    `ContractResponse` struct internally for host-side bookkeeping —
- *    it carries an extracted `otp_state` alongside the response.
- * 3. **`node/app/src/services/wasm.rs:200`** then unwraps the struct with
- *    `Ok((response.response, tx_back))`, discarding the `otp_state` field
- *    and returning only the inner `Value` across the `WasmExecutor` trait
- *    boundary.
- * 4. `node/service/src/action.rs` serialises that plain `Value` through
- *    the session channel.
+ * 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
@@ -1220,10 +1216,10 @@ declare function parseContractResponse<T = unknown>(raw: string, schema?: Contra
 
 /**
  * KYC types for the `tee:user/contracts::kyc-status` short-poll
- * function added in MAT-1202.
+ * function.
  *
- * The shape mirrors `tee_contracts/user/src/kyc_status.rs::KycStatusResponse`.
- * Keep the two in sync — the bytes go straight from the contract
+ * The shape mirrors the `kyc-status` wire response.
+ * The bytes go straight from the contract
  * through the JSON-RPC envelope into [[T3nClient.kycStatus]].
  */
 
@@ -1238,7 +1234,7 @@ declare function parseContractResponse<T = unknown>(raw: string, schema?: Contra
  *   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 (T3-TS-024 §3.4). Should not
+ *   couldn't be matched to any user. Should not
  *   happen in the MetaMask flow but the contract surfaces it for
  *   completeness.
  */
@@ -1276,8 +1272,8 @@ interface KycStatus {
     error?: string;
 }
 /**
- * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults match
- * T3-TS-026 §8.4: poll fast for the first 30 seconds, then back
+ * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults:
+ * poll fast for the first 30 seconds, then back
  * off, and bail after 5 minutes.
  */
 interface KycPollCadence {
@@ -1295,7 +1291,7 @@ interface KycPollCadence {
 }
 /**
  * Optional knobs for [[T3nClient.kycStatusPoll]]. Most callers won't
- * touch any of these — the §8.4 defaults are baked in.
+ * touch any of these — the cadence defaults are baked in.
  */
 interface KycPollOptions {
     /**
@@ -1315,7 +1311,7 @@ interface KycPollOptions {
     onUpdate?: (status: KycStatus) => void;
     /**
      * Override one or more cadence fields. Anything not specified
-     * uses the §8.4 defaults from [[DEFAULT_KYC_POLL_CADENCE]].
+     * uses the defaults from [[DEFAULT_KYC_POLL_CADENCE]].
      */
     cadence?: Partial<KycPollCadence>;
     /**
@@ -1327,7 +1323,7 @@ interface KycPollOptions {
 }
 /**
  * Default cadence used by [[T3nClient.kycStatusPoll]] when the caller
- * doesn't override `cadence.*`. Matches T3-TS-026 §8.4 verbatim.
+ * doesn't override `cadence.*`.
  */
 declare const DEFAULT_KYC_POLL_CADENCE: KycPollCadence;
 /**
@@ -1343,12 +1339,12 @@ declare const TERMINAL_KYC_STATUSES: ReadonlySet<KycStatusKind>;
  * minutes but Veriff is still working" UX.
  */
 declare class KycStatusTimeoutError extends T3nError {
-    /** The §8.4 timeout the helper exhausted. */
+    /** 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 §8.4 timeout the helper exhausted. */
+    /** The timeout (ms) the helper exhausted before a terminal status arrived. */
     timeoutMs: number, 
     /** The last `pending` snapshot before timeout, if any. */
     lastStatus?: KycStatus | undefined);
@@ -1377,10 +1373,10 @@ declare class T3nClient {
     private readonly effectiveBaseUrl;
     /**
      * Server-minted session ID, set by {@link handshake} from the
-     * `Session-Id` response header (pentest M-1 / MAT-983). `null`
-     * until the handshake completes. Client code cannot set it — the
-     * former `config.sessionId` hook was the session-fixation vector
-     * this fix closes.
+     * `Session-Id` response header. `null`
+     * until the handshake completes. Client code cannot set it — a
+     * client-supplied session id is rejected, closing the
+     * session-fixation vector.
      */
     private sessionId;
     /**
@@ -1413,7 +1409,7 @@ declare class T3nClient {
      * Stored in a dedicated field instead of reusing `wasmState`
      * because the two meanings — "in-flight state machine" vs
      * "finalized payload" — are semantically different and merging
-     * them invites the bug-class Devin flagged in PR #1140.
+     * them re-introduces the bug-class this guard exists to prevent.
      */
     private finalizedPayload;
     private did;
@@ -1477,7 +1473,7 @@ declare class T3nClient {
     /**
      * Fetch the caller's usage feed — balance plus a bounded slice of
      * recent token-ledger entries (charges, mints, transfers), newest
-     * first. T3-TS-030 Phase 1D step A (`token.get-usage`).
+     * first (`token.get-usage`).
      *
      * `limit` defaults to 50 server-side and clamps silently to
      * `1..=200`. `afterSeq` is the inclusive upper-bound `seq_no`
@@ -1497,8 +1493,8 @@ declare class T3nClient {
     /**
      * Execute an action and JSON-decode the response.
      *
-     * The server strips its internal `ContractResponse` wrapper at
-     * `node/app/src/services/wasm.rs` before sending — the string returned
+     * The server strips its internal `ContractResponse` wrapper
+     * before sending — the string returned
      * by {@link execute} is the contract's decoded return value directly
      * (no `{response, otp_state}` envelope). This helper is a typed
      * `JSON.parse` with optional schema validation so callers stop
@@ -1513,8 +1509,7 @@ declare class T3nClient {
     executeAndDecode<T = unknown>(payload: unknown, schema?: ContractResponseSchema<T>): Promise<T>;
     /**
      * Build the canonical `ExecuteActionRequest` shape the server
-     * expects in `node/primitives/src/action.rs::ExecuteActionRequest`
-     * (`script_name`, `script_version`, `function_name`, `input`,
+     * expects (`script_name`, `script_version`, `function_name`, `input`,
      * optional `pii_did`) and dispatch it through {@link execute}.
      *
      * Two pieces of glue live here that every typed user-contract
@@ -1545,7 +1540,7 @@ declare class T3nClient {
      *
      * Backed by the `tee:user/get-self-eth-address` contract function,
      * which delegates to the signing host's `get-user-eth-address`
-     * primitive (T3-TS-027 §7.1). The request carries no body; the
+     * primitive. The request carries no body; the
      * authenticated user's DID is read from session context by the host.
      *
      * Requires the session to be Authenticated (same precondition as
@@ -1557,7 +1552,7 @@ declare class T3nClient {
     getSelfEthAddress(): Promise<string | null>;
     /**
      * Enumerate every wallet the authenticated user currently controls
-     * under T3-TS-028 multi-wallet custody.
+     * under multi-wallet custody.
      *
      * `primary` is the identity-bearing wallet — same address
      * {@link getSelfEthAddress} returns, same address the host signs
@@ -1567,7 +1562,7 @@ declare class T3nClient {
      * only via an explicit sign-with-wallet flow — never ambient.
      *
      * Backed by `tee:user/list-user-wallets` which delegates to the
-     * signing host's `list-user-wallets` primitive. See T3-TS-028 §7.1.
+     * signing host's `list-user-wallets` primitive.
      *
      * @throws if unauthenticated, if the node rejects the action, or if
      *   the response shape is unexpected.
@@ -1585,7 +1580,7 @@ declare class T3nClient {
      * this wallet onto a new owner, `Abandoned` if
      * {@link removeUserWithWalletAbandonment} was called on the last
      * owner. Public-safe data: DIDs + timestamps + reason codes only,
-     * no key material or PII. See T3-TS-028 §4.1.
+     * no key material or PII.
      *
      * @param walletAddress 0x-prefixed 40-char hex Ethereum address.
      * @throws if the node rejects the action or if the response is not
@@ -1603,7 +1598,7 @@ declare class T3nClient {
      * exists as an opt-in alternative to {@link removeUser}, which
      * refuses when the DID owns wallets. Callers must sweep funds
      * off-chain BEFORE calling this if they want to retain access —
-     * the host does not reconcile balances. See T3-TS-028 §6.2.
+     * the host does not reconcile balances.
      *
      * Requires the session to be Authenticated (SelfOnly delegation).
      *
@@ -1617,7 +1612,7 @@ declare class T3nClient {
      * Returns the current snapshot of the authenticated user's Level 2
      * KYC state — see [[KycStatus]] for the four possible terminal /
      * non-terminal values. The caller usually wants
-     * [[kycStatusPoll]] (which loops with §8.4 cadence until a
+     * [[kycStatusPoll]] (which loops with backoff cadence until a
      * terminal status arrives), but the bare snapshot is useful for
      * pages that need to render the user's standing without waiting
      * (e.g. account-status views, "did the user finish KYC last time
@@ -1696,7 +1691,7 @@ declare class T3nClient {
      * `t3n.user-input.kyc.1` once every Level-1 field is present, and
      * commits the write.
      *
-     * **Pre-condition** (MAT-1374): the DID must already have a
+     * **Pre-condition**: the DID must already have a
      * verified email — either because {@link otpVerify} bound one or
      * because the session carries a proving authenticator (OIDC /
      * Email auth). Calls without proof are rejected with
@@ -1743,7 +1738,7 @@ declare class T3nClient {
         attestations?: unknown;
         keys?: Record<string, unknown>;
         /**
-         * MAT-1618 testnet self-admit, propagated to the inner
+         * Testnet self-admit, propagated to the inner
          * {@link submitUserInput} call. Inspect `result.tenantAdmit` for
          * the outcome.
          */
@@ -1754,7 +1749,7 @@ declare class T3nClient {
      * Poll `kyc-status` until a terminal status arrives or the
      * configured timeout elapses.
      *
-     * Cadence defaults to T3-TS-026 §8.4: 2-second interval for the
+     * Cadence defaults to: 2-second interval for the
      * first 30 seconds, then 5 seconds, with a 5-minute hard cap.
      * Override via `opts.cadence` if you need different numbers
      * (e.g. tests that don't want to wait the full 30 seconds before
@@ -1780,7 +1775,7 @@ declare class T3nClient {
     kycStatusPoll(opts?: KycPollOptions): Promise<KycStatus>;
     /**
      * The server-minted session ID once handshake has completed, or
-     * `null` beforehand (pentest M-1 / MAT-983).
+     * `null` beforehand.
      */
     getSessionId(): SessionId | null;
     getStatus(): SessionStatus;
@@ -1862,23 +1857,20 @@ declare class T3nClient {
      *
      * JSON-RPC `error.message` is the generic category string
      * ("Invalid params", "Internal error", …). The node attaches the
-     * actionable text and per-request correlation id in `error.data`
-     * — see `node/api/src/responses/rpc.rs::from_service_error`.
+     * actionable text and per-request correlation id in `error.data`.
      * Extract both so callers (and toasts that only render `.message`)
-     * get the real reason plus an id an operator can grep in
-     * `api::error` logs.
+     * get the real reason plus an id an operator can grep in the logs.
      *
-     * T3-TS-030 chargepoint denials surface as a typed
+     * Chargepoint denials surface as a typed
      * `InsufficientCreditError` so frontends can branch on
      * `instanceof` to render an "out of credit" UI without
-     * prefix-matching the message themselves. Wire format is pinned
-     * by `api/src/error.rs::service_insufficient_credit_wire_format_is_stable`.
+     * prefix-matching the message themselves. The wire format is stable.
      */
     private throwIfRpcError;
     private sendMultipartRpcRequest;
     /**
      * Capture the server-minted `Session-Id` from the last handshake
-     * response headers (pentest M-1 / MAT-983). Validates shape so a
+     * response headers. Validates shape so a
      * broken or MITM'd response fails loudly instead of leaving a
      * garbage value in the client. Idempotent: only the first valid
      * mint per session is honoured — subsequent handshake RPC legs
@@ -1959,10 +1951,10 @@ declare function createRandomHandler(): GuestToHostHandler;
 declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
 
 /**
- * User-to-Agent Delegation (T3-TS-030).
+ * User-to-Agent Delegation.
  *
  * TypeScript reference implementation of the delegation credential and
- * envelope shapes defined in `node/tee_contracts/delegation-types`.
+ * envelope shapes defined by the delegation wire contract.
  *
  * The wire shape is byte-for-byte identical to the Rust source — pinned
  * by the KAT fixtures under `tests/kat/`. Specifically:
@@ -2049,11 +2041,11 @@ interface PayrollRunRequest {
     /** `employee_id` → previous-cycle baseline net disbursement, cents (decimal string). */
     historical_baselines: Record<string, string>;
     /**
-     * Per-employee disbursement flag threshold, in cents. Mirrors
-     * `PayrollRunRequest::individual_disbursement_threshold_cents` on the Rust
-     * side. When absent the Rust contract applies its own default (SGD 15,000;
-     * `DEFAULT_INDIVIDUAL_THRESHOLD_CENTS`). When present, the value is
-     * included in the wire shape and participates in the request hash.
+     * Per-employee disbursement flag threshold, in cents. Mirrors the
+     * payroll request's individual-disbursement threshold field.
+     * When absent the contract applies its own default (SGD 15,000). When
+     * present, the value is included in the wire shape and participates in
+     * the request hash.
      */
     individual_disbursement_threshold_cents?: bigint;
 }
@@ -2091,7 +2083,7 @@ interface SignDelegationResponse {
 declare function b64uEncode(input: Uint8Array): string;
 /**
  * Encode raw bytes to base64url-no-pad (RFC 4648 §5 with padding
- * dropped). The same encoding T3-TS-030 wire-shape uses for binary
+ * dropped). The same encoding the wire-shape uses for binary
  * fields (`agent_pubkey`, `vc_id`, `nonce`, `agent_sig`, `user_sig`,
  * `request_hash`, `credential_jcs`).
  *
@@ -2154,7 +2146,7 @@ interface BuildDelegationCredentialOpts {
  */
 declare function buildDelegationCredential(opts: BuildDelegationCredentialOpts): DelegationCredential;
 /**
- * Body-level validation matching `delegation-types::validate_credential_body`,
+ * Body-level validation matching the delegation credential-body validation,
  * minus the `now`/`max_validity_secs` checks (which are caller-supplied).
  * Throws with a message identifying the offending invariant.
  */
@@ -2172,7 +2164,7 @@ declare function signCredential(jcs: Uint8Array, secret: Uint8Array): {
 };
 /**
  * Recover the 20-byte ETH address that signed `msg` under EIP-191.
- * Mirrors `delegation-types::eth_recover_eip191`.
+ * Mirrors the delegation contract's EIP-191 address recovery.
  *
  * **Signature malleability — accepted by design.** This routine does
  * not enforce low-s. EIP-2 mandates low-s for *transaction* signatures,
@@ -2185,8 +2177,8 @@ declare function signCredential(jcs: Uint8Array, secret: Uint8Array): {
 declare function ethRecoverEip191(msg: Uint8Array, sig: Uint8Array): Uint8Array;
 /**
  * Sign the agent-side invocation pre-image. The signature is raw
- * compact ECDSA (64 bytes) over `sha256(preimage)` — what
- * `delegation-types::verify_agent_sig` accepts as the 64-byte form.
+ * compact ECDSA (64 bytes) over `sha256(preimage)` — the 64-byte form
+ * the delegation contract accepts.
  */
 declare function signAgentInvocation(preimage: Uint8Array, secret: Uint8Array): Uint8Array;
 /**
@@ -2221,9 +2213,6 @@ interface SignCustodialResult {
  * The client must be constructed with an authenticated {@link T3nClient}
  * instance and the node's base URL; `signCustodial` sends the credential
  * body to the TEE and returns the signed bytes.
- *
- * Reference: `node/tests/harness/src/payroll_seed.rs` (the
- * `tee:delegation.sign` invocation at line 550).
  */
 declare class DelegationCustodialClient {
     private readonly t3n;
@@ -2687,13 +2676,13 @@ declare function isObject(value: unknown): value is Record<string, unknown>;
  */
 declare function assertShape<T>(value: unknown, guard: (v: unknown) => v is T, where: string): T;
 
+type Environment = "testnet" | "production";
+declare const NODE_URLS: Record<Environment, string>;
+
 /**
  * Configuration types for T3n SDK
  */
-/**
- * Environment type for SDK configuration
- */
-type Environment = "local" | "staging" | "testnet" | "production" | "test";
+
 /**
  * SDK configuration structure
  */
@@ -2790,11 +2779,6 @@ declare function validateConfig(config: unknown): ConfigValidationResult;
  * `${nodeUrl}/status` (`encaps_key` field) and cached per-URL.
  */
 
-/**
- * Default node URLs per environment. Override at runtime via `setNodeUrl()`
- * or by passing `baseUrl` to `T3nClient`.
- */
-declare const NODE_URLS: Record<Environment, string>;
 /** DKG attestation bundle from the cluster. */
 interface DkgAttestation {
     /** Sorted base58 peer IDs that participated in DKG. */
@@ -2860,5 +2844,187 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MAX_FUNCTIONS_PER_CREDENTIAL, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, PAYROLL_FUNCTIONS_V1, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, revokeDelegation, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, validateConfig, validateCredentialBody, verifyDkgAttestation, verifyTdxQuote };
-export type { AgeBand, AuthInput, BalanceRow, BuildDelegationCredentialOpts, BuildPayrollDirectInvocationOpts, BuildPayrollInvocationOpts, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteOrgDataActionOptions, ExpenseClaim, GetUsageOptions, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ResidencyCategory, RevokeDelegationOpts, RevokeDelegationResult, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TokenTxKind, Transport, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WritersGetInput };
+type TenantSdkEnvironment = "testnet" | "production";
+
+/**
+ * Minimal structural seam for the authenticated base client a TenantClient
+ * dispatches through. Kept as an interface (rather than the concrete
+ * `T3nClient` class) so tests can inject mocks and so a control-plane-only
+ * client — which lacks `getUsage` — also satisfies it.
+ */
+interface TenantBaseClient {
+    execute(payload: unknown): Promise<string>;
+    executeWithBlob(payload: unknown, blob: Uint8Array | Blob): Promise<string>;
+    executeAndDecode?<T = unknown>(payload: unknown): Promise<T>;
+    /**
+     * Token usage feed (`token.get-usage`). Present on the full
+     * authenticated base `T3nClient`; absent on a control-plane-only client.
+     */
+    getUsage?(opts?: GetUsageOptions): Promise<UsagePage>;
+}
+interface TenantClientConfig {
+    environment?: TenantSdkEnvironment;
+    /** Node URL for `getScriptVersion` during business contract execution. Falls back to `baseUrl`. */
+    endpoint?: string;
+    t3n?: TenantBaseClient;
+    baseUrl?: string;
+    tenantDid?: string;
+    tenantScriptName?: string;
+}
+type TenantStatus = "pending" | "active" | "suspended";
+interface TenantMeResponse {
+    tenant: string;
+    eth_address: string;
+    label: string;
+    status: TenantStatus;
+    quotas: unknown;
+    created_at: string;
+}
+/**
+ * Response shape for the testnet self-admit path. `granted_credits`
+ * is `null` on the idempotent `already-admitted` retry.
+ */
+interface TenantSelfAdmitResult {
+    status: "admitted" | "already-admitted";
+    tenant: string;
+    granted_credits: number | null;
+}
+type MapVisibility = string;
+type WriterSet = "all" | "All" | {
+    only: number[];
+} | {
+    Only: number[];
+};
+type ReaderSet = "all" | "All" | {
+    only: number[];
+} | {
+    Only: number[];
+};
+interface MapCreateInput {
+    tail: string;
+    visibility: MapVisibility;
+    writers: WriterSet;
+    readers?: ReaderSet;
+    keyValidator?: unknown;
+}
+interface MapUpdateInput {
+    visibility?: MapVisibility;
+    writers?: WriterSet;
+    readers?: ReaderSet;
+    keyValidator?: unknown;
+    adminReadable?: boolean;
+    extraReadGrants?: string[];
+    extraWriteGrants?: string[];
+}
+interface MapResponse {
+    name: string;
+    tail: string;
+    visibility: MapVisibility;
+    writers: WriterSet;
+    readers: ReaderSet;
+    metadata?: Record<string, unknown>;
+}
+interface ContractPublishInput {
+    tail: string;
+    version: string;
+    wasm: Uint8Array | Blob;
+    /**
+     * Optional hex SHA-256 of the source bundle this WASM was built from, for the
+     * WASM scanner's source-to-bytecode attestation. Use the
+     * same algorithm as the scanner / `tee-contract-source-hash`. Stored verbatim
+     * on chain; never gates execution. Omit if you are not publishing source.
+     */
+    source_hash?: string;
+}
+interface ContractExecuteInput {
+    version: string;
+    functionName: string;
+    input?: unknown;
+}
+
+type JsonObject = Record<string, unknown>;
+interface TenantExecutionSession {
+    executeAndDecode<T = unknown>(payload: unknown, schema?: ContractResponseSchema<T>): Promise<T>;
+}
+interface ExecuteBusinessContractOptions<T = unknown> {
+    tenant: string;
+    contract: string;
+    functionName: string;
+    input: Record<string, unknown>;
+    schema?: ContractResponseSchema<T>;
+}
+type TenantMapCreateInput = MapCreateInput;
+type TenantMapUpdatePatch = MapUpdateInput;
+type TenantContractPublishInput = ContractPublishInput;
+type TenantContractExecuteInput = ContractExecuteInput;
+declare class TenantNamespace {
+    private readonly client;
+    constructor(client: TenantClient);
+    claim(): Promise<unknown>;
+    me(): Promise<unknown>;
+}
+declare class TenantMapsNamespace {
+    private readonly client;
+    constructor(client: TenantClient);
+    create(input: MapCreateInput): Promise<unknown>;
+    update(tail: string, patch: MapUpdateInput): Promise<unknown>;
+    delete(tail: string): Promise<unknown>;
+}
+declare class TenantContractsNamespace {
+    private readonly client;
+    constructor(client: TenantClient);
+    publish(input: ContractPublishInput): Promise<unknown>;
+    register(input: ContractPublishInput): Promise<unknown>;
+    disable(tail: string): Promise<unknown>;
+    enable(tail: string): Promise<unknown>;
+    unregister(tail: string): Promise<unknown>;
+    execute(tail: string, input: ContractExecuteInput): Promise<unknown>;
+    private contractStateChange;
+}
+declare class TenantTokenNamespace {
+    private readonly client;
+    constructor(client: TenantClient);
+    /**
+     * Fetch the caller's token usage feed (current balance + a paginated
+     * slice of recent ledger entries — charges, mints, transfers).
+     *
+     * Thin pass-through to the authenticated base `T3nClient`'s
+     * `token.get-usage` RPC. Requires `config.t3n` to be a full
+     * authenticated `T3nClient` that exposes `getUsage`; the narrow control
+     * client used for control-plane-only flows does not.
+     */
+    getUsage(opts?: GetUsageOptions): Promise<UsagePage>;
+}
+/**
+ * TenantClient exposes tenant SDK client-side capabilities.
+ *
+ * Supports tenant control-plane helpers, direct tenant-local business contract
+ * execution, and config inspection.
+ */
+declare class TenantClient {
+    readonly config: Readonly<TenantClientConfig>;
+    readonly tenant: TenantNamespace;
+    readonly maps: TenantMapsNamespace;
+    readonly contracts: TenantContractsNamespace;
+    readonly token: TenantTokenNamespace;
+    constructor(config: TenantClientConfig);
+    getEnvironment(): TenantClientConfig["environment"];
+    canonicalName(tail: string): string;
+    controlPayload(functionName: string, input: unknown): Promise<JsonObject>;
+    executeControl(functionName: string, input: unknown): Promise<unknown>;
+    executeBusinessContract<T = unknown>(session: TenantExecutionSession, options: ExecuteBusinessContractOptions<T>): Promise<T>;
+}
+
+declare class TenantSdkValidationError extends Error {
+    constructor(message: string);
+}
+declare class UnsupportedTenantSdkOperationError extends Error {
+    constructor(message: string);
+}
+
+declare function tenantDidHex(tenantDid: string): string;
+declare function validateTail(tail: string): string;
+declare function canonicalTenantName(tenantDid: string, tail: string): string;
+
+export { AGENT_PUBKEY_LEN, AuthMethod, AuthenticationError, ContractResponseError, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, DELEGATION_CREDENTIAL_DOMAIN, DELEGATION_INVOCATION_DOMAIN, DelegationCustodialClient, ETH_SIG_LEN, HandshakeError, HttpTransport, KycStatusTimeoutError, LogLevel, MAX_FUNCTIONS_PER_CREDENTIAL, MockTransport, NODE_URLS, NONCE_LEN, OrgDataClient, PAYROLL_FUNCTIONS_V1, REQUEST_HASH_LEN, RpcError, SessionExpiredError, SessionOrgDataClient, SessionStateError, SessionStatus, T3nClient, T3nError, TERMINAL_KYC_STATUSES, TenantClient, TenantContractsNamespace, TenantMapsNamespace, TenantNamespace, TenantSdkValidationError, TenantTokenNamespace, UnsupportedTenantSdkOperationError, UserUpsertError, VC_ID_LEN, WasmError, _b64uEncode, assertShape, b64uDecodeStrict, b64uEncodeBytes, buildDelegationCredential, buildInvocationPreimage, buildPayrollDirectInvocation, buildPayrollInvocation, bytesToString, canonicalTenantName, canonicaliseCredential, canonicaliseRequest, clearKeyCache, compactDidFromBytes, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, decodeWasmErrorMessage, eip191Digest, ethRecoverEip191, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, isDataGetResponse, isDataListResponse, isMutationResponse, isObject, isOrgContractGrants, isOrgPolicyMeta, isOrgWriters, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, parseContractResponse, redactSecrets, redactSecretsFromJson, requestHash, revokeDelegation, setEnvironment, setGlobalLogLevel, setNodeUrl, signAgentInvocation, signCredential, stringToBytes, tenantDidHex, validateConfig, validateCredentialBody, validateTail, verifyDkgAttestation, verifyTdxQuote };
+export type { AgeBand, AuthInput, BalanceRow, BuildDelegationCredentialOpts, BuildPayrollDirectInvocationOpts, BuildPayrollInvocationOpts, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractExecuteInput, ContractPublishInput, ContractResponseSchema, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationCredential, DelegationCustodialClientOpts, DelegationEnvelope, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, Did, Direction, DkgAttestation, DkgVerifyResult, EmployeeRecord, EmploymentStatus, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, ExpenseClaim, GetUsageOptions, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, Logger, MapCreateInput, MapResponse, MapUpdateInput, MapVisibility, MutationResponse, OidcAuthInput, OidcCredentials, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollInvocation, PayrollInvocationDelegated, PayrollInvocationDirect, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, QuoteVerifyResult, ReaderSet, ResidencyCategory, RevokeDelegationOpts, RevokeDelegationResult, SdkConfig, SessionCrypto, SessionId, SetGrantsInput, SetWritersInput, SignCustodialResult, SignDelegationResponse, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TokenTxKind, Transport, UpdateMetaInput, UsageEntry, UsagePage, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WriteDataInput, WriterSet, WritersGetInput };