@terminal3/t3n-sdk 4.30.0 → 4.32.0

package/dist/index.d.ts

@@ -933,931 +933,1298 @@ declare class ContractResponseError extends T3nError {
 declare function parseContractResponse<T = unknown>(raw: string, schema?: ContractResponseSchema<T>): T;
 
 /**
- * Agent-auth grants — the standing on-chain authority a user delegates to
- * an agent (envelope-free authorisation).
+ * Org-data wire types mirroring the org-data contract wire shapes.
  *
- * `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:authorisations/contracts` (the policy's owning contract) 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.
- */
-/** 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[];
-}
-/**
- * The full agent-auth policy document in the camelCase write shape:
- * the per-agent grants plus the document-level discovery grants.
+ * 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 `BoundGrant` inside `OrgContractGrants.grants`) are not
+ * deeply validated — see `utils/shape.ts` for the rationale.
  *
- * `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.
+ * Reference: the org-data wire contract.
  */
-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.
+ * Validity time-box on an agent-edge grant — serialised under the JSON key
+ * `window`. Both bounds are optional unix-seconds; an omitted bound is
+ * defaulted contract-side (`valid_from_secs` → now, `valid_until_secs` → now +
+ * operator cap). Mirrors the org-data `Validity` wire shape. Absent bounds
+ * are omitted from the wire (never sent as `null`).
  */
-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[];
+interface Validity {
+    valid_from_secs?: number;
+    valid_until_secs?: number;
 }
-/** 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[];
-}
-/**
- * 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[];
-};
-/**
- * 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).
- */
-declare function mergeDiscoverDids(existing: string[], additions: string[]): string[];
-/**
- * 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.
- */
-declare function mergeAgentAuthEntries(existing: AgentAuthEntry[], newEntries: AgentAuthEntry[]): AgentAuthMergeResult;
-
 /**
- * KYC types for the `tee:user/contracts::kyc-status` short-poll
- * function.
+ * A grantee-bound capability grant — the element of BOTH grant-management
+ * surfaces: the org edge (`org-policy-set-grants` input / `org-grants-get`
+ * output) and the flat agent edge (`agent-auth-get` output / `agent-auth-update`
+ * input). Stored inline on the unified `ROLE_ASSIGNMENTS_MAP` edge record.
  *
- * The shape mirrors the `kyc-status` wire response.
- * The bytes go straight from the contract
- * through the JSON-RPC envelope into [[T3nClient.kycStatus]].
+ * Mirrors the org-data `BoundGrant` wire shape verbatim (snake_case, no casing
+ * transform): `grantee` followed by the flattened capability body. The org edge
+ * populates only `functions` + `scopes`; the agent edge additionally carries the
+ * qualifiers `version_req` / `read_scopes` / `allowed_hosts` and the validity
+ * `window`. All qualifier fields are optional and omitted from the wire when
+ * absent (never sent as `null`), so an org grant simply leaves them unset.
  */
-
+interface BoundGrant {
+    /** The principal (`did:t3n:<40-hex>`) this grant applies to — a user or an
+     *  agent DID. */
+    grantee: string;
+    /** Target contract id (canonical name, e.g. `"tee:z-payroll/contracts"`), or
+     *  `"*"`. On a read this echoes the queried contract. */
+    contract_id: string;
+    /** WIT function names the grantee may invoke (e.g. `"set-records"`; `["*"]`
+     *  matches all). */
+    functions: string[];
+    /** Data scope paths the grantee may access (e.g. `"example/records"`). */
+    scopes: string[];
+    /** Agent edge only: optional semver requirement; omitted matches any version. */
+    version_req?: string;
+    /** Agent edge only: direct-read scopes the grantee may enumerate itself — a
+     *  subset of `scopes` (enforced contract-side). */
+    read_scopes?: string[];
+    /** Agent edge only: egress hosts the grantee may reach for this contract. */
+    allowed_hosts?: string[];
+    /** Agent edge only: optional validity time-box. */
+    window?: Validity;
+}
 /**
- * Terminal status for a Level 2 KYC verification, plus `pending`.
+ * Policy record for an organisation's data tier.
  *
- * - `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.
+ * Mirrors the org-data policy-meta wire shape.
  */
-type KycStatusKind = "pending" | "verified" | "rejected" | "orphan";
+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;
 /**
- * Snapshot returned by `tee:user/contracts::kyc-status`.
+ * Effective org policy view returned by `org-policy-view`.
  *
- * 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.
+ * 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 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[];
+interface OrgPolicyView {
     /**
-     * Provider-supplied reason for `rejected`, when available.
+     * 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`).
      */
-    error?: string;
+    effective_validity_secs: number;
 }
+/** Shallow runtime guard for {@link OrgPolicyView}. */
+declare function isOrgPolicyView(value: unknown): value is OrgPolicyView;
 /**
- * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults:
- * poll fast for the first 30 seconds, then back
- * off, and bail after 5 minutes.
+ * Caller-scoped admin status returned by `org-am-i-admin`.
+ *
+ * Reports only whether the **calling** session's DID is in the org's admin
+ * list — never the roster itself (contrast {@link OrgPolicyMeta}, returned by
+ * the admin-gated `org-policy-get`). Readable by any authenticated session.
+ * Mirrors the org-data `AmIAdminResponse` wire shape.
  */
-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;
+interface OrgAdminStatus {
+    /** Whether the calling session is an admin of the queried org. */
+    is_admin: boolean;
 }
+/** Shallow runtime guard for {@link OrgAdminStatus}. */
+declare function isOrgAdminStatus(value: unknown): value is OrgAdminStatus;
 /**
- * Optional knobs for [[T3nClient.kycStatusPoll]]. Most callers won't
- * touch any of these — the cadence defaults are baked in.
+ * Standard response returned by all policy write and data mutation operations.
+ *
+ * Mirrors the org-data `MutationResponse` wire shape.
  */
-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 MutationResponse {
     /**
-     * Provider id to poll. Defaults to the contract default
-     * (`"veriff"` in phase one). Mirrored on the wire as
-     * `input.provider_id`.
+     * `"created"`, `"updated"`, `"deleted"`, or — for the agent-card mutations —
+     * `"published"` / `"unpublished"`.
      */
-    providerId?: string;
+    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;
 }
 /**
- * Default cadence used by [[T3nClient.kycStatusPoll]] when the caller
- * doesn't override `cadence.*`.
+ * 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 const DEFAULT_KYC_POLL_CADENCE: KycPollCadence;
+declare function isMutationResponse(value: unknown): value is MutationResponse;
 /**
- * Subset of [[KycStatusKind]] that ends a poll. `pending` is the
- * only non-terminal value.
+ * Response type alias for org-writers-get.
+ *
+ * The wire body is `{ writers: string[] }` where each entry is
+ * `did:t3n:<40-hex>`.
  */
-declare const TERMINAL_KYC_STATUSES: ReadonlySet<KycStatusKind>;
+interface OrgWriters {
+    writers: string[];
+}
+/** Shallow runtime guard for {@link OrgWriters}. */
+declare function isOrgWriters(value: unknown): value is OrgWriters;
 /**
- * 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.
+ * Response type alias for org-grants-get.
+ *
+ * The wire body echoes the `contract_id` alongside the grant list.
  */
-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 OrgContractGrants {
+    contract_id: string;
+    grants: BoundGrant[];
 }
-
 /**
- * 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.
+ * Shallow runtime guard for {@link OrgContractGrants}.
  *
- * Bytes flow directly from the contract
- * through the JSON-RPC envelope into the SDK wrappers
- * (`T3nClient.otpRequest`, `T3nClient.otpVerify`,
- * `T3nClient.submitUserInput`).
+ * Validates the immediate envelope (`contract_id: string`, `grants:
+ * array`) without recursing into each `BoundGrant`. 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 isOrgContractGrants(value: unknown): value is OrgContractGrants;
 /**
- * OTP delivery channel. Matches the `OtpContactChannel` Rust enum
- * with `serde(rename_all = "snake_case")`.
+ * One grant inside a role: a capability body (functions + scopes, without the
+ * grantee, which is bound at assignment time) plus the target contract.
+ * Mirrors the org-data `RoleGrant` wire shape.
  */
-type OtpChannel = "email" | "sms";
+interface RoleGrant {
+    /** Target contract (canonical name, e.g. `"tee:z-payroll/contracts"`). */
+    contract_id: string;
+    /** WIT function names this grant confers. */
+    functions: string[];
+    /** Data scope paths this grant confers (canonicalised lowercase). */
+    scopes: string[];
+}
 /**
- * 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.
- *
- * - `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".
+ * A role: a named bundle of grants and/or composed sub-roles.
+ * Mirrors the org-data `RoleDefinition` wire shape.
  */
-interface OtpRequestResult {
-    contact: string;
-    channel: OtpChannel;
-    expiresAtSec?: number;
-    status?: string;
-    txHash?: string;
-    isNewProfile?: boolean;
+interface RoleDefinition {
+    /** Org-unique role identifier (slug; function-name grammar). */
+    role_id: string;
+    /** Human-facing label. */
+    label: string;
+    /** Composite: other role ids in the same org whose grants this role confers. */
+    includes: string[];
+    /** Grants this role confers directly. */
+    grants: RoleGrant[];
 }
 /**
- * Input to `T3nClient.otpVerify`. `otpCode` is mandatory; `request`
- * repeats the same discriminated contact shape as {@link OtpRequestInput}.
+ * The roles assigned to one grantee within one org.
+ * Mirrors the org-data `RoleAssignments` wire shape.
  */
-interface OtpVerifyInput {
-    otpCode: string;
-    request: OtpRequestInput;
+interface RoleAssignments {
+    /** Assigned role ids. */
+    roles: string[];
+}
+/** Response for `org-role-get`; `role` is `null` when the id is unknown. */
+interface RoleGetResponse {
+    role: RoleDefinition | null;
+}
+/** Shallow runtime guard for {@link RoleGetResponse}. */
+declare function isRoleGetResponse(value: unknown): value is RoleGetResponse;
+/** Response for `org-role-assignments-get`. */
+interface RoleAssignmentsResponse {
+    /** Echoed back so callers don't need to track which request this answers. */
+    grantee_did: string;
+    /** The grantee's assigned role ids (empty when none). */
+    roles: string[];
 }
+/** Shallow runtime guard for {@link RoleAssignmentsResponse}. */
+declare function isRoleAssignmentsResponse(value: unknown): value is RoleAssignmentsResponse;
 /**
- * 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.
+ * Input for `listAgents` — the org plus optional pagination. Omit both `cursor`
+ * and `limit` for the first page at the default limit; pass a previous
+ * response's `next_cursor` back as `cursor` to fetch the following page.
  */
-interface OtpMergeSuggestion {
-    existingDid: string;
-    currentDid: string;
-    email?: string;
-    phone?: string;
-    channel: OtpChannel;
+interface ListAgentsInput {
+    orgDid: string;
+    /** Opaque cursor from a previous response's `next_cursor`. */
+    cursor?: string;
+    /** Maximum agents to return in this page. */
+    limit?: number;
 }
 /**
- * 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.
+ * One org-owned agent in a {@link ListAgentsResponse}: the agent's DID, its
+ * display name, and the number of distinct contracts it can access via a direct
+ * grant. Mirrors the org-data `AgentSummary` wire shape. The name comes from the
+ * agent's private card (falling back to the DID), so the FE no longer needs to
+ * fetch each `public:agent_cards` entry to render the roster.
  */
-interface OtpVerifyResult {
-    txHash?: string;
+interface AgentSummary {
+    /** The agent's DID (`did:t3n:<40-hex>`). */
     did: string;
-    channel: OtpChannel;
-    email?: string;
-    phone?: string;
-    status?: string;
-    mergeSuggestion?: OtpMergeSuggestion;
-    isNewProfile?: boolean;
+    /** The agent's display name, from its private card (DID when unavailable). */
+    name: string;
+    /** Count of distinct contracts the agent holds a direct grant on. */
+    contract_count: number;
 }
-/**
- * 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;
+/** Response for `org-data-list-agents`. */
+interface ListAgentsResponse {
+    /** One PAGE of the org's org-owned agents, sorted by DID. */
+    agents: AgentSummary[];
+    /** Opaque cursor for the next page; absent on the last page. */
+    next_cursor?: string;
 }
+/** A human member's org role. The closed wire domain of {@link HumanMember}. */
+type MemberRole = "admin" | "member";
 /**
- * Input to `T3nClient.submitUserInput`. Maps onto the slim
- * `user-upsert` request shape: `{ profile, organisation_did?,
- * attestations?, keys? }`.
+ * Input for `listHumanMembers` — the org plus optional pagination. Omit both
+ * `cursor` and `limit` for the first page at the default limit; pass a previous
+ * response's `next_cursor` back as `cursor` to fetch the following page.
  */
-interface SubmitUserInputArgs {
-    profile: UserInputProfile;
-    organisationDid?: string;
-    attestations?: unknown;
-    keys?: Record<string, unknown>;
-    /**
-     * 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`.
-     */
-    requireExistingUser?: boolean;
-    /**
-     * 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`.
-     */
-    becomeDevTenant?: boolean;
+interface ListHumanMembersInput {
+    orgDid: string;
+    /** Opaque cursor from a previous response's `next_cursor`. */
+    cursor?: string;
+    /** Maximum members to return in this page. */
+    limit?: number;
 }
 /**
- * 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
- *   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.
+ * One direct human member: DID plus org role. No profile PII (name/email are
+ * out of scope and owned by `tee:user`). Mirrors the org-data `HumanMember`
+ * wire shape.
  */
-type TenantAdmitStatus = "admitted" | "already-admitted" | "refused";
-interface TenantAdmitProjection {
-    status: TenantAdmitStatus;
-    grantedCredits?: string;
-    reason?: string;
-    detail?: string;
+interface HumanMember {
+    /** The member's DID (`did:t3n:<40-hex>`). */
+    did: string;
+    /** The member's org role. */
+    role: MemberRole;
+}
+/** Response for `org-data-list-human-members`. */
+interface ListHumanMembersResponse {
+    /** One PAGE of the org's direct human members, sorted by DID. */
+    members: HumanMember[];
+    /** Opaque cursor for the next page; absent on the last page. */
+    next_cursor?: string;
+}
+/** Shallow runtime guard for {@link ListHumanMembersResponse}. */
+declare function isListHumanMembersResponse(value: unknown): value is ListHumanMembersResponse;
+/** Shallow runtime guard for {@link ListAgentsResponse}. */
+declare function isListAgentsResponse(value: unknown): value is ListAgentsResponse;
+/** 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;
+/** Secret shape discriminator (mirrors the contract `SecretKind`). */
+type SecretKind = "single_value" | "json";
+/** Metadata common to every {@link SecretView} entry. */
+interface SecretViewBase {
+    /** Secret name (the `(org, name)` key tail). */
+    name: string;
+    /** Monotonic version, bumped on each value rotation and ACL edit. */
+    version: number;
+    /** Unix seconds of the most recent write. */
+    updated_at_secs: number;
 }
 /**
- * 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 redacted per-secret summary `org-secret-list` returns — a discriminated
+ * union on `kind`. The value is NEVER present: a single-value exposes only its
+ * last four characters and a json secret only its sorted top-level field names.
  */
-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;
+type SecretView = (SecretViewBase & {
+    kind: "single_value";
+    /** Last four characters of the value (whole value when ≤ 4 chars). */
+    last4: string;
+}) | (SecretViewBase & {
+    kind: "json";
+    /** Sorted top-level object field names (keys only, no values). */
+    field_names: string[];
+});
+/** Shallow runtime guard for {@link SecretView}. */
+declare function isSecretView(value: unknown): value is SecretView;
+/**
+ * Full secret record returned by `org-secret-get` — the value IS included
+ * (the deliberate read-back path the READ axis exists for), along with all
+ * three ACLs.
+ */
+interface SecretRecord {
+    name: string;
+    kind: SecretKind;
+    /** The value as text: the scalar for a single-value, canonical JSON object for a json secret. */
+    value: string;
+    version: number;
+    /** READ axis — DIDs allowed to read the value back. */
+    reader_dids: string[];
+    /** READ axis — role ids allowed to read the value back. */
+    reader_roles: string[];
+    /** MANAGE axis — DIDs allowed to rotate the value. */
+    manager_dids: string[];
+    /** MANAGE axis — role ids allowed to rotate the value. */
+    manager_roles: string[];
+    /** USE axis — canonical contract ids allowed to have the value injected. */
+    contract_allowlist: string[];
+    created_at_secs: number;
+    updated_at_secs: number;
+    /** DID of the caller who last wrote the record. */
+    updated_by: string;
+}
+/** Shallow runtime guard for {@link SecretRecord}. */
+declare function isSecretRecord(value: unknown): value is SecretRecord;
+/** Response for `org-secret-list`: redacted per-kind views, no values. */
+interface SecretListResponse {
+    secrets: SecretView[];
+}
+/** Shallow runtime guard for {@link SecretListResponse}. */
+declare function isSecretListResponse(value: unknown): value is SecretListResponse;
+/** 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;
 /**
- * Discriminator for {@link UserUpsertError}. Mirrors the
- * `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.
- *   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.
+ * Return shape of `agentCardGet` — composed client-side from the generic
+ * `org-data-get` read of the card's entry (there is no card-specific read
+ * operation on the contract). To check whether a public copy exists, probe
+ * the anonymous `GET /api/agent-card/{did}` endpoint.
  */
-type UserUpsertErrorKind = "EmailNotVerified" | "LegacyField" | "UserNotFound";
+interface AgentCardResponse {
+    /** The agent whose card this is (`did:t3n:<40-hex>`). */
+    agent_did: string;
+    /** The stored card JSON body, verbatim. */
+    card: string;
+}
+/** Shallow runtime guard for {@link AgentCardResponse}. */
+declare function isAgentCardResponse(value: unknown): value is AgentCardResponse;
 /**
- * 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.
+ * Legacy direct-route org-data envelope shape retained for compatibility.
  *
- * Throw site: `T3nClient.submitUserInput` (and friends) when the
- * contract returns a string error matching the
- * `<code>:<detail>` shape.
+ * 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 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;
+interface OrgDataActionWire {
+    nonce: string;
+    user_did: string;
+    authenticator_id: string;
+    contract_id: string;
+    function: string;
+    args_hash: string;
+    expires_at_secs: number;
+    signature: string;
 }
 
 /**
- * Token-metering wire shapes.
+ * Agent-auth grants — the standing on-chain authority a user delegates to
+ * an agent (envelope-free authorisation).
  *
- * 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 document is one flat list of {@link BoundGrant} rows plus the
+ * document-level discovery grants: `{ grants, discover_dids }`. Each grant's
+ * `grantee` is the agent DID it authorises, so there is no per-agent grouping —
+ * a user's whole delegation surface is the single `grants` array. Reads
+ * (`agent-auth-get`) and writes (`agent-auth-update`) on
+ * `tee:authorisations/contracts` (the policy's owning contract) 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.
+ *
+ * A grant carries `functions`, the agent's delegated org-data `scopes`, the
+ * direct-enumerable `read_scopes`, egress `allowed_hosts`, an optional semver
+ * `version_req`, and an optional validity `window`. The ≤ cap *length* check is
+ * enforced contract-side at write time; the expiry gate is host-side at read
+ * time.
+ *
+ * The SDK is a literal snake_case mirror of the wire: {@link BoundGrant} IS the
+ * wire grant shape, so reads and writes pass through untouched — there is no
+ * casing transform. The only glue here is the read-merge-write helper
+ * ({@link mergeGrants}) that lets a single-grant write preserve every other row
+ * (the contract has no per-field merge; the document IS the new state).
  */
+
 /**
- * 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.
- */
-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;
+ * The full agent-auth policy document — the shape of BOTH the `agent-auth-get`
+ * output and the `agent-auth-update` input (they are identical). A flat list of
+ * grant rows plus the document-level discovery grants; mirrors the contract
+ * `AgentAuthDoc` wire shape verbatim (snake_case).
+ *
+ * `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 grant — because discovery must surface contracts the agent
+ * cannot yet call. The node's discovery gate additionally requires the calling
+ * agent to be the `grantee` of at least one grant (subject binding), so an
+ * unregistered agent discovers nothing regardless of this list.
+ *
+ * The document IS the new state on a write: an empty `grants` list revokes all
+ * agent access, and an empty `discover_dids` persists an empty discovery-grant
+ * list (there is no per-field merge). Use {@link mergeGrants} /
+ * {@link mergeDiscoverDids} to read-merge-write a single grant without dropping
+ * the rest.
+ */
+interface AgentAuthDoc {
+    /** Every standing agent-edge grant, each keyed by its `grantee` agent DID. */
+    grants: BoundGrant[];
+    /** Document-level discovery grants (`did:t3n:<40-hex>` entries). */
+    discover_dids: string[];
+}
+/**
+ * Decode an `agent-auth-get` response into an {@link AgentAuthDoc}. The wire is
+ * already snake_case, so grant rows pass through unchanged — this only defaults
+ * a `null` / absent response (the empty policy) and a missing field to an empty
+ * list. NOT a casing transform.
+ */
+declare function parseAgentAuthDoc(response: unknown): AgentAuthDoc;
+interface GrantsMergeResult {
+    /** Full merged grant list, ready for `agent-auth-update`. */
+    grants: BoundGrant[];
+    /** `"<grantee> → <contract_id>"` rows preserved from the existing policy. */
+    preservedRows: 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"`.
+ * Merge new grant rows into the existing flat list with `(grantee, contract_id)`
+ * union semantics: an existing row whose `(grantee, contract_id)` matches a new
+ * row is replaced; every other existing row is preserved (and reported in
+ * `preservedRows` as an audit aid). New rows for a `(grantee, contract_id)` not
+ * already present are appended.
  */
-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;
-};
+declare function mergeGrants(existing: BoundGrant[], additions: BoundGrant[]): GrantsMergeResult;
 /**
- * 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`).
+ * Order-preserving deduplicating union of discovery-grant DID lists — the
+ * read-merge-write counterpart of {@link mergeGrants} for the document-level
+ * `discover_dids` (the contract rejects duplicate entries, so the union must
+ * dedupe).
  */
-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 function mergeDiscoverDids(existing: string[], additions: string[]): string[];
+
 /**
- * Response shape of `token.get-usage` — caller's balance plus a
- * paginated slice of their most-recent `token:tx_log` entries.
+ * KYC types for the `tee:user/contracts::kyc-status` short-poll
+ * function.
  *
- * `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.
- */
-interface UsagePage {
-    balance: BalanceRow;
-    entries: UsageEntry[];
-    next_cursor?: number | null;
-}
-/**
- * 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".
+ * The shape mirrors the `kyc-status` wire response.
+ * The bytes go straight from the contract
+ * through the JSON-RPC envelope into [[T3nClient.kycStatus]].
  */
-interface GetUsageOptions {
-    limit?: number;
-    after_seq?: number;
-    kinds?: TokenTxKind[];
-}
 
 /**
- * Tenant audit-event wire shapes.
+ * Terminal status for a Level 2 KYC verification, plus `pending`.
  *
- * 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`.
+ * - `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.
  */
+type KycStatusKind = "pending" | "verified" | "rejected" | "orphan";
 /**
- * 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;
-}
-/**
- * One archived batch — the events committed in a single tenant dispatch.
- * Every event in a batch shares the same `subject` / `actor` / `vc_id`.
- */
-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[];
-}
-/**
- * `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.
- */
-interface AuditPage {
-    batches: AuditBatch[];
-    next_cursor?: string | null;
-}
-/**
- * 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.
- */
-interface GetAuditEventsOptions {
-    pii_did?: string;
-    limit?: number;
-    cursor?: string;
-}
-
-/**
- * Agent-activity audit-log wire shapes (the node's `auditlog` RPC).
- *
- * Mirrors `service::activity_audit::{ActivityReport, ReportEntry}` and
- * `primitives::audit_log::AuditLogEntry`. One entry per audited contract
- * dispatch — who called, for whom, which contract + function, and how it
- * ended. Entries are reconstructed from the append-only ledger on read, so
- * `seq_no` (the ledger index) and `hash` are derived server-side rather than
- * stored with the record.
- *
- * Scope is the caller's **own organisation**, resolved node-side from the
- * session DID: there is no scope parameter, and a page carries **every
- * member's** activity in that org, not just the caller's own. Metadata only —
- * DIDs, never display names, call arguments, or payloads.
- */
-/**
- * Whether the actor is a registered agent or a human / self principal.
- * Decided node-side by an existence check on the actor DID in the agent
- * registry — never inferred from the DID's shape.
- */
-type ActivityCallerType = "agent" | "human";
-/**
- * Host-stamped outcome of an audited dispatch.
+ * Snapshot returned by `tee:user/contracts::kyc-status`.
  *
- * - `success` — the business transaction committed.
- * - `denied` — authorisation refused the call.
- * - `error` — the call was allowed but failed / rolled back.
+ * 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.
  */
-type ActivityOutcome = "success" | "denied" | "error";
-/** One audited call. */
-interface ActivityEntry {
+interface KycStatus {
+    /** Terminal status if reached, otherwise `pending`. */
+    status: KycStatusKind;
     /**
-     * Ledger index of the entry — its unique, ordered id. Use it as the row key
-     * and as the ordering key: it is monotonic, whereas {@link timestamp_ms} is
-     * per-node wall clock.
+     * Provider being polled. Echoed back so callers that didn't
+     * supply one see the contract's default (`"veriff"` in phase one).
      */
-    seq_no: number;
-    /** Hex SHA-256 of the stored entry (64 chars) — read-time tamper evidence. */
-    hash: string;
+    provider: string;
     /**
-     * Call time in Unix ms, stamped on the node that took the request. NOT a
-     * cluster-assigned time, so entries from different nodes can be skewed by
-     * their clock offset — order by {@link seq_no}, not by this.
+     * 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.
      */
-    timestamp_ms: number;
-    /** Agent vs human, from the agent-registry check on {@link actor}. */
-    caller_type: ActivityCallerType;
-    /** DID that actually invoked the contract. */
-    actor: string;
+    updatedAt?: number;
     /**
-     * DID of the owner the caller acted for. Equals {@link actor} on a self /
-     * own-authority call — never null.
+     * VC ids appended for this provider, in append order. Empty for
+     * `pending` / `rejected` / `orphan`.
      */
-    on_behalf_of: string;
+    vcIds: string[];
     /**
-     * Organisation the acting principal belongs to — the report's scope key, so
-     * it is identical on every row of a page. Falls back to `on_behalf_of` when
-     * that principal is in no organisation.
+     * Provider-supplied reason for `rejected`, when available.
      */
-    org: string;
-    /** Contract that ran, e.g. `tee:user/contracts`. */
-    contract: string;
-    /** Contract function invoked, e.g. `user-upsert`. */
-    function: string;
-    /** success / denied / error — host-stamped from the dispatch result. */
-    outcome: ActivityOutcome;
+    error?: string;
+}
+/**
+ * Polling cadence for [[T3nClient.kycStatusPoll]]. Defaults:
+ * poll fast for the first 30 seconds, then back
+ * off, and bail after 5 minutes.
+ */
+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;
     /**
-     * Role ids the acting authority carried at call time: the actor's role in
-     * the organisation on a self-call, the roles the owner granted the agent on
-     * a delegated call. Omitted when the authority carried no role (direct
-     * grants, an individual, or an entry recorded before roles were captured).
-     * On a `denied` entry this is the caller's *claimed* authority, not a
-     * validated one.
+     * Maximum total time to spend polling before rejecting with
+     * [[KycStatusTimeoutError]]. Default: 300_000 (5 minutes).
      */
-    roles?: string[];
+    timeoutMs: number;
 }
 /**
- * One page of the organisation's activity report — **newest first**, i.e.
- * descending `seq_no`.
+ * Optional knobs for [[T3nClient.kycStatusPoll]]. Most callers won't
+ * touch any of these — the cadence defaults are baked in.
  */
-interface ActivityReport {
-    entries: ActivityEntry[];
+interface KycPollOptions {
     /**
-     * Cursor to resume from — pass it back as
-     * {@link GetActivityLogOptions.before_seq}. `null` once the requested window
-     * is exhausted.
-     *
-     * A live cursor with **fewer rows than `limit`, or none at all**, is normal:
-     * the node also caps how much ledger one call decrypts, and that cap can trip
-     * before the window ends. Page until this is `null`, never on a short or
-     * empty page.
+     * 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.
      */
-    next_seq: number | null;
-}
-/** Params for one activity-report page. All optional; `{}` is valid. */
-interface GetActivityLogOptions {
-    /** Window start, Unix ms, inclusive. Defaults to 0 (no lower bound). */
-    from_ms?: number;
-    /** Window end, Unix ms, inclusive. Defaults to unbounded. */
-    to_ms?: number;
+    signal?: AbortSignal;
     /**
-     * Cursor, inclusive — the highest `seq_no` this page may return. Omitted ⇒
-     * start at the newest entry in the window. Pages walk downwards, so this is
-     * the previous page's {@link ActivityReport.next_seq}.
+     * 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.
      */
-    before_seq?: number;
+    onUpdate?: (status: KycStatus) => void;
     /**
-     * Rows returned this page. Clamped server-side to 1–1000 (default 200).
-     *
-     * A page can still be shorter than this (or empty) with a live `next_seq` —
-     * the node's own scan cap can trip first. See {@link ActivityReport.next_seq}.
+     * Override one or more cadence fields. Anything not specified
+     * uses the defaults from [[DEFAULT_KYC_POLL_CADENCE]].
      */
-    limit?: number;
+    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;
+}
+/**
+ * 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.
+ */
+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);
 }
 
 /**
- * Contract-discovery wire shapes.
+ * Wire types for the explicit `otp-request` /
+ * `otp-verify` / slim `user-upsert` exports on `tee:user/contracts`
+ * (`tee:user@2.0.0`).
  *
- * Field-for-field mirrors of the node's `contracts.list` and `delegation.check`
- * JSON-RPC responses (`service::contract_discovery::{ListedContract,
- * ListContractsResponse}` and `service::grant_check::{GrantRef,
- * GrantCheckResponse}`). Both methods are session-authenticated plaintext reads
- * dispatched over `/api/rpc` — the same posture as `token.get-usage` — so the
- * SDK wrappers return the parsed `result` object directly.
+ * 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`).
  */
-/** The navigable starting points of the discovery funnel. */
-type ListContractsScope = "core" | "org" | "self";
-/** Params for `contracts.list` (every field optional; `{}` lists core). */
-interface ListContractsParams {
-    /** `"core"` (default) | `"org"` | `"self"`. */
-    scope?: ListContractsScope;
-    /** Target org DID (required for scope `"org"`). */
-    org_did?: string;
-    /** The member the agent acts for (required for scope `"org"` / `"self"`). */
-    pii_did?: string;
-    /** Page offset (defaults to 0 server-side). */
-    offset?: number;
-    /** Page size (defaults + clamped server-side). */
-    limit?: number;
-}
-/** Contract kind — `"core"` platform system contract, `"tenant"` z-space. */
-type ContractKind = "core" | "tenant";
-/** One contract as presented by `contracts.list`. */
-interface ListedContract {
-    /** Canonical name: `tee:<name>` for core, `z:<tid>:<tail>` for tenant. */
-    name: string;
-    kind: ContractKind;
-    /** Current registered version; `null` when the contract is not registered. */
-    version: string | null;
-    /** Descriptor summary, or empty when no descriptor is published. */
-    summary: string;
-    /** Descriptor tags, or empty. */
-    tags: string[];
-    /** Owning DID: the org DID (org mode) or the member's own DID (self mode). */
-    owner_org_did?: string;
-    /**
-     * Human-facing short name: the trailing segment of `name` (`payroll` from
-     * `z:<tid>:payroll`, `user` from `tee:user`). Present this to people instead
-     * of the full canonical `name`, which remains the dispatch key.
-     */
-    short_name: string;
-}
-/** Response body for `contracts.list`. */
-interface ListContractsResult {
-    scope: string;
-    contracts: ListedContract[];
-    next_offset: number | null;
+
+/**
+ * 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.
+ *
+ * - `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;
 }
-/** Which standing grant a satisfied/missing entry refers to. */
-type DelegationGrantKind = "agent_auth" | "user_grant";
-/** Params for `delegation.check` (the generic capability read). */
-interface GrantCheckParams {
-    /** The target contract whose requirements are checked. */
-    contract: string;
-    /** The member the agent wants to act for (the subject). */
-    pii_did: string;
-    /** Functions the intended action needs. */
-    functions: string[];
-    /** Org-data scopes the intended action needs. */
-    scopes: string[];
+/**
+ * Input to `T3nClient.otpVerify`. `otpCode` is mandatory; `request`
+ * repeats the same discriminated contact shape as {@link OtpRequestInput}.
+ */
+interface OtpVerifyInput {
+    otpCode: string;
+    request: OtpRequestInput;
 }
-/** One grant requirement — satisfied or missing. */
-interface DelegationGrantRef {
-    grant: DelegationGrantKind;
-    /** The target contract's canonical name. */
-    contract: string;
-    functions: string[];
-    scopes: 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;
 }
 /**
- * Response for `delegation.check`: the `agent_auth ∩ UserGrant` verdict.
+ * Response returned by `otp-verify`. Mirrors the OTP-verify wire response.
  *
- * `disclosed` is `true` only when the agent is registered under `pii_did`, so
- * org-side status was safe to disclose; `false` yields the uniform,
- * non-disclosive verdict (`authorised:false, satisfied:[], missing:[]`) that is
- * byte-invariant to the requested capability (R5 anti-enumeration).
+ * - `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 GrantCheckResult {
-    authorised: boolean;
-    disclosed: boolean;
-    satisfied: DelegationGrantRef[];
-    missing: DelegationGrantRef[];
+interface OtpVerifyResult {
+    txHash?: string;
+    did: string;
+    channel: OtpChannel;
+    email?: string;
+    phone?: string;
+    status?: string;
+    mergeSuggestion?: OtpMergeSuggestion;
+    isNewProfile?: boolean;
 }
-
 /**
- * T3n Client - Main SDK class
+ * 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.
  *
- * Provides a simple interface for establishing secure sessions with T3n nodes.
- * All cryptographic complexity is handled in WASM components.
+ * `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;
+}
 /**
- * Main T3n SDK Client
+ * Input to `T3nClient.submitUserInput`. Maps onto the slim
+ * `user-upsert` request shape: `{ profile, organisation_did?,
+ * attestations?, keys? }`.
  */
-declare class T3nClient {
-    private readonly config;
-    private readonly transport;
+interface SubmitUserInputArgs {
+    profile: UserInputProfile;
+    organisationDid?: string;
+    attestations?: unknown;
+    keys?: Record<string, unknown>;
     /**
-     * Resolved node base URL. Snapshotted in the constructor so the
-     * typed contract wrappers (`kycStatus`, `getSelfEthAddress`, …)
-     * can call `getScriptVersion()` against the same host the
-     * transport talks to. Used only by the `script_version: "latest"`
-     * resolution path in {@link executeUserContract}.
+     * 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`.
      */
-    private readonly effectiveBaseUrl;
+    requireExistingUser?: boolean;
     /**
-     * Server-minted session ID, set by {@link handshake} from the
-     * `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.
+     * 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`.
      */
-    private sessionId;
+    becomeDevTenant?: boolean;
+}
+/**
+ * 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
+ *   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.
+ */
+interface SubmitUserInputResult {
+    txHash?: string;
+    refusedFields?: string[];
+    mergeSuggestion?: OtpMergeSuggestion;
+    userFound?: boolean;
     /**
-     * Set by {@link sendRpcRequest} when an `auth.handshake` RPC is
-     * actually issued. Decouples the "flow completed without talking
-     * to a server" case (unit-test mocks that only exercise handler
-     * delegation) from the real "server must mint the id" invariant:
-     * we only enforce the mint requirement when a round-trip happened.
+     * Testnet self-admit projection. Present only when the caller
+     * set `becomeDevTenant: true` on the request.
      */
-    private handshakeSentRpc;
-    private readonly logger;
-    private readonly encryption;
+    tenantAdmit?: TenantAdmitProjection;
+}
+/**
+ * Discriminator for {@link UserUpsertError}. Mirrors the
+ * `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.
+ *   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.
+ */
+type UserUpsertErrorKind = "EmailNotVerified" | "LegacyField" | "UserNotFound";
+/**
+ * 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.
+ *
+ * Throw site: `T3nClient.submitUserInput` (and friends) when the
+ * contract returns a string error matching the
+ * `<code>:<detail>` shape.
+ */
+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;
+}
+
+/**
+ * Token-metering wire shapes.
+ *
+ * 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.
+ *
+ * `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.
+ */
+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;
+}
+/**
+ * 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`).
+ */
+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;
+}
+/**
+ * Response shape of `token.get-usage` — caller's balance plus a
+ * paginated slice of their most-recent `token:tx_log` entries.
+ *
+ * `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.
+ */
+interface UsagePage {
+    balance: BalanceRow;
+    entries: UsageEntry[];
+    next_cursor?: number | null;
+}
+/**
+ * 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 GetUsageOptions {
+    limit?: number;
+    after_seq?: number;
+    kinds?: TokenTxKind[];
+}
+
+/**
+ * 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`.
+ */
+/**
+ * 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;
+}
+/**
+ * One archived batch — the events committed in a single tenant dispatch.
+ * Every event in a batch shares the same `subject` / `actor` / `vc_id`.
+ */
+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[];
+}
+/**
+ * `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.
+ */
+interface AuditPage {
+    batches: AuditBatch[];
+    next_cursor?: string | null;
+}
+/**
+ * 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.
+ */
+interface GetAuditEventsOptions {
+    pii_did?: string;
+    limit?: number;
+    cursor?: string;
+}
+
+/**
+ * Agent-activity audit-log wire shapes (the node's `auditlog` RPC).
+ *
+ * Mirrors `service::activity_audit::{ActivityReport, ReportEntry}` and
+ * `primitives::audit_log::AuditLogEntry`. One entry per audited contract
+ * dispatch — who called, for whom, which contract + function, and how it
+ * ended. Entries are reconstructed from the append-only ledger on read, so
+ * `seq_no` (the ledger index) and `hash` are derived server-side rather than
+ * stored with the record.
+ *
+ * Scope is the caller's **own organisation**, resolved node-side from the
+ * session DID: there is no scope parameter, and a page carries **every
+ * member's** activity in that org, not just the caller's own. Metadata only —
+ * DIDs, never display names, call arguments, or payloads.
+ */
+/**
+ * Whether the actor is a registered agent or a human / self principal.
+ * Decided node-side by an existence check on the actor DID in the agent
+ * registry — never inferred from the DID's shape.
+ */
+type ActivityCallerType = "agent" | "human";
+/**
+ * Host-stamped outcome of an audited dispatch.
+ *
+ * - `success` — the business transaction committed.
+ * - `denied` — authorisation refused the call.
+ * - `error` — the call was allowed but failed / rolled back.
+ */
+type ActivityOutcome = "success" | "denied" | "error";
+/** One audited call. */
+interface ActivityEntry {
+    /**
+     * Ledger index of the entry — its unique, ordered id. Use it as the row key
+     * and as the ordering key: it is monotonic, whereas {@link timestamp_ms} is
+     * per-node wall clock.
+     */
+    seq_no: number;
+    /** Hex SHA-256 of the stored entry (64 chars) — read-time tamper evidence. */
+    hash: string;
+    /**
+     * Call time in Unix ms, stamped on the node that took the request. NOT a
+     * cluster-assigned time, so entries from different nodes can be skewed by
+     * their clock offset — order by {@link seq_no}, not by this.
+     */
+    timestamp_ms: number;
+    /** Agent vs human, from the agent-registry check on {@link actor}. */
+    caller_type: ActivityCallerType;
+    /** DID that actually invoked the contract. */
+    actor: string;
+    /**
+     * DID of the owner the caller acted for. Equals {@link actor} on a self /
+     * own-authority call — never null.
+     */
+    on_behalf_of: string;
+    /**
+     * Organisation the acting principal belongs to — the report's scope key, so
+     * it is identical on every row of a page. Falls back to `on_behalf_of` when
+     * that principal is in no organisation.
+     */
+    org: string;
+    /** Contract that ran, e.g. `tee:user/contracts`. */
+    contract: string;
+    /** Contract function invoked, e.g. `user-upsert`. */
+    function: string;
+    /** success / denied / error — host-stamped from the dispatch result. */
+    outcome: ActivityOutcome;
+    /**
+     * Role ids the acting authority carried at call time: the actor's role in
+     * the organisation on a self-call, the roles the owner granted the agent on
+     * a delegated call. Omitted when the authority carried no role (direct
+     * grants, an individual, or an entry recorded before roles were captured).
+     * On a `denied` entry this is the caller's *claimed* authority, not a
+     * validated one.
+     */
+    roles?: string[];
+}
+/**
+ * One page of the organisation's activity report — **newest first**, i.e.
+ * descending `seq_no`.
+ */
+interface ActivityReport {
+    entries: ActivityEntry[];
+    /**
+     * Cursor to resume from — pass it back as
+     * {@link GetActivityLogOptions.before_seq}. `null` once the requested window
+     * is exhausted.
+     *
+     * A live cursor with **fewer rows than `limit`, or none at all**, is normal:
+     * the node also caps how much ledger one call decrypts, and that cap can trip
+     * before the window ends. Page until this is `null`, never on a short or
+     * empty page.
+     */
+    next_seq: number | null;
+}
+/** Params for one activity-report page. All optional; `{}` is valid. */
+interface GetActivityLogOptions {
+    /** Window start, Unix ms, inclusive. Defaults to 0 (no lower bound). */
+    from_ms?: number;
+    /** Window end, Unix ms, inclusive. Defaults to unbounded. */
+    to_ms?: number;
+    /**
+     * Cursor, inclusive — the highest `seq_no` this page may return. Omitted ⇒
+     * start at the newest entry in the window. Pages walk downwards, so this is
+     * the previous page's {@link ActivityReport.next_seq}.
+     */
+    before_seq?: number;
+    /**
+     * Rows returned this page. Clamped server-side to 1–1000 (default 200).
+     *
+     * A page can still be shorter than this (or empty) with a live `next_seq` —
+     * the node's own scan cap can trip first. See {@link ActivityReport.next_seq}.
+     */
+    limit?: number;
+}
+
+/**
+ * Contract-discovery wire shapes.
+ *
+ * Field-for-field mirrors of the node's `contracts.list` and `delegation.check`
+ * JSON-RPC responses (`service::contract_discovery::{ListedContract,
+ * ListContractsResponse}` and `service::grant_check::{GrantRef,
+ * GrantCheckResponse}`). Both methods are session-authenticated plaintext reads
+ * dispatched over `/api/rpc` — the same posture as `token.get-usage` — so the
+ * SDK wrappers return the parsed `result` object directly.
+ */
+/** The navigable starting points of the discovery funnel. */
+type ListContractsScope = "core" | "org" | "self";
+/** Params for `contracts.list` (every field optional; `{}` lists core). */
+interface ListContractsParams {
+    /** `"core"` (default) | `"org"` | `"self"`. */
+    scope?: ListContractsScope;
+    /** Target org DID (required for scope `"org"`). */
+    org_did?: string;
+    /** The member the agent acts for (required for scope `"org"` / `"self"`). */
+    pii_did?: string;
+    /** Page offset (defaults to 0 server-side). */
+    offset?: number;
+    /** Page size (defaults + clamped server-side). */
+    limit?: number;
+}
+/** Contract kind — `"core"` platform system contract, `"tenant"` z-space. */
+type ContractKind = "core" | "tenant";
+/** One contract as presented by `contracts.list`. */
+interface ListedContract {
+    /** Canonical name: `tee:<name>` for core, `z:<tid>:<tail>` for tenant. */
+    name: string;
+    kind: ContractKind;
+    /** Current registered version; `null` when the contract is not registered. */
+    version: string | null;
+    /** Descriptor summary, or empty when no descriptor is published. */
+    summary: string;
+    /** Descriptor tags, or empty. */
+    tags: string[];
+    /** Owning DID: the org DID (org mode) or the member's own DID (self mode). */
+    owner_org_did?: string;
+    /**
+     * Human-facing short name: the trailing segment of `name` (`payroll` from
+     * `z:<tid>:payroll`, `user` from `tee:user`). Present this to people instead
+     * of the full canonical `name`, which remains the dispatch key.
+     */
+    short_name: string;
+}
+/** Response body for `contracts.list`. */
+interface ListContractsResult {
+    scope: string;
+    contracts: ListedContract[];
+    next_offset: number | null;
+}
+/** Which standing grant a satisfied/missing entry refers to. */
+type DelegationGrantKind = "agent_auth" | "org_grant";
+/** Params for `delegation.check` (the generic capability read). */
+interface GrantCheckParams {
+    /** The target contract whose requirements are checked. */
+    contract: string;
+    /** The member the agent wants to act for (the subject). */
+    pii_did: string;
+    /** Functions the intended action needs. */
+    functions: string[];
+    /** Org-data scopes the intended action needs. */
+    scopes: string[];
+}
+/** One grant requirement — satisfied or missing. */
+interface DelegationGrantRef {
+    grant: DelegationGrantKind;
+    /** The target contract's canonical name. */
+    contract: string;
+    functions: string[];
+    scopes: string[];
+}
+/**
+ * Response for `delegation.check`: the `agent_auth ∩ org_grant` verdict.
+ *
+ * `disclosed` is `true` only when the agent is registered under `pii_did`, so
+ * org-side status was safe to disclose; `false` yields the uniform,
+ * non-disclosive verdict (`authorised:false, satisfied:[], missing:[]`) that is
+ * byte-invariant to the requested capability (R5 anti-enumeration).
+ */
+interface GrantCheckResult {
+    authorised: boolean;
+    disclosed: boolean;
+    satisfied: DelegationGrantRef[];
+    missing: DelegationGrantRef[];
+}
+
+/**
+ * T3n Client - Main SDK class
+ *
+ * Provides a simple interface for establishing secure sessions with T3n nodes.
+ * All cryptographic complexity is handled in WASM components.
+ */
+
+/**
+ * Main T3n SDK Client
+ */
+declare class T3nClient {
+    private readonly config;
+    private readonly transport;
+    /**
+     * Resolved node base URL. Snapshotted in the constructor so the
+     * typed contract wrappers (`kycStatus`, `getSelfEthAddress`, …)
+     * can call `getContractVersion()` against the same host the
+     * transport talks to. Used only by the `contract_version: "latest"`
+     * resolution path in {@link executeUserContract}.
+     */
+    private readonly effectiveBaseUrl;
+    /**
+     * Server-minted session ID, set by {@link handshake} from the
+     * `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;
+    /**
+     * Set by {@link sendRpcRequest} when an `auth.handshake` RPC is
+     * actually issued. Decouples the "flow completed without talking
+     * to a server" case (unit-test mocks that only exercise handler
+     * delegation) from the real "server must mint the id" invariant:
+     * we only enforce the mint requirement when a round-trip happened.
+     */
+    private handshakeSentRpc;
+    private readonly logger;
+    private readonly encryption;
     private status;
     /**
      * In-flight WASM state-machine bytes. Holds the opaque state
@@ -2035,7 +2402,7 @@ declare class T3nClient {
      * Generic capability check (`delegation.check`) — the
      * node-backed source for the MCP `checkDelegation` funnel tool.
      *
-     * Returns the `agent_auth ∩ UserGrant` verdict for `(agent, contract,
+     * Returns the `agent_auth ∩ org_grant` verdict for `(agent, contract,
      * pii_did)`: whether the acting agent (resolved from the session) holds the
      * standing grants that `contract`'s `functions` / `scopes` need for member
      * `pii_did`. The org half is vacuous for no-org (Individual-owned) targets,
@@ -2274,10 +2641,10 @@ declare class T3nClient {
      *    (org-admin gated; idempotent on an already-absent membership). The host
      *    membership gate makes the detach effective immediately.
      * 2. `org-remove-member-grants` — sweep the member from the org's
-     *    per-contract `UserGrant` lists, so the capability does not silently
+     *    per-contract `BoundGrant` lists, so the capability does not silently
      *    reactivate if the member later rejoins.
      *
-     * The member's `agent_auth` delegations are self-scoped (`AGENT_AUTH_MAP` is a
+     * The member's `agent_auth` delegations are self-scoped (the agent-auth edge in `ROLE_ASSIGNMENTS_MAP` is a
      * per-user document an admin cannot reach), so this cannot sweep them; the host
      * membership gate denies them regardless, and the member's own session can run
      * {@link revokeAgentAuthForOrg} for full cleanup.
@@ -2308,7 +2675,7 @@ declare class T3nClient {
      * Revoke the caller's own agent delegations scoped to one org
      * (detach-cascade `agent_auth` half). Dispatches
      * `agent-auth-revoke-org` on `tee:user/contracts` (**SelfOnly**): every
-     * `ScriptGrant` targeting a `z:<orgTid>:*` contract is removed from the
+     * agent-edge grant targeting a `z:<orgTid>:*` contract is removed from the
      * caller's own agent-auth document.
      *
      * @param orgTid - the org's z-space tenant id (`did:t3n:<hex>` or bare
@@ -2320,25 +2687,27 @@ declare class T3nClient {
      * grants delegated to agents. Dispatches `agent-auth-get` on
      * `tee:authorisations/contracts` (the policy's owning contract), which is
      * **SelfOnly**, so this always returns the caller's own
-     * `AGENT_AUTH_MAP[self]` document.
+     * agent-auth edge in `ROLE_ASSIGNMENTS_MAP`.
      *
-     * @returns the full policy document (normalised to the camelCase write
-     *   shape): the per-agent `agents` entries plus the document-level
-     *   `discoverDids` discovery grants
+     * @returns the full policy document as the flat snake_case wire shape: the
+     *   `grants` list (each row's `grantee` is the authorised agent DID) plus the
+     *   document-level `discover_dids` discovery grants
      * @throws if the session is not authenticated, or the contract refuses
      */
-    getAgentAuth(): Promise<AgentAuthPolicy>;
+    getAgentAuth(): Promise<AgentAuthDoc>;
     /**
      * Authorise an agent for one contract on the caller's own behalf
      * (envelope-free authorisation). Read-merge-writes the
-     * caller's `AGENT_AUTH_MAP[self]` document via `agent-auth-update`
-     * (**SelfOnly**) with script-level union semantics, so other contracts'
-     * grants for this or any agent survive untouched.
+     * caller's agent-auth edge in `ROLE_ASSIGNMENTS_MAP` via `agent-auth-update`
+     * (**SelfOnly**) with `(grantee, contract_id)` union semantics, so other
+     * contracts' grants for this or any agent survive untouched.
      *
-     * Carries the new `scopes` + validity fields: the delegated
-     * org-data scopes and an optional `[validFromSecs, validUntilSecs]`
-     * window. The ≤ cap *length* check is enforced contract-side at write
-     * time; the expiry gate is host-side at read time.
+     * The grant is the flat wire {@link BoundGrant}: its `grantee` is the agent
+     * DID being authorised, and it carries `functions`, the delegated org-data
+     * `scopes`, direct-read `read_scopes`, egress `allowed_hosts`, an optional
+     * semver `version_req`, and an optional validity `window`. The ≤ cap *length*
+     * check is enforced contract-side at write time; the expiry gate is host-side
+     * at read time.
      *
      * This is the write surface `getDelegationInstructions` produces the
      * parameters for. The caller MUST be the delegating user, authenticated as
@@ -2350,38 +2719,38 @@ declare class T3nClient {
      * standing discovery), and any `options.discoverDids` are unioned in
      * (order-preserving, deduplicated).
      *
-     * @param agentDid - the agent DID being authorised
-     * @param grant - the single script grant to set (contract, functions,
-     *   scopes, validity, egress hosts)
+     * @param grant - the single grant to set — a {@link BoundGrant} whose
+     *   `grantee` is the agent DID being authorised (contract_id, functions,
+     *   scopes, window, egress hosts)
      * @param options - optional `discoverDids` to union into the document's
      *   discovery grants (org DIDs for org-mode `listContracts`, the caller's
      *   own DID for self mode)
-     * @returns the script rows preserved from the existing policy (audit aid)
+     * @returns the grant rows preserved from the existing policy (audit aid)
      * @throws if the session is not authenticated, or the contract refuses
      */
-    updateAgentAuth(agentDid: string, grant: AgentAuthScriptGrant, options?: {
+    updateAgentAuth(grant: BoundGrant, options?: {
         discoverDids?: string[];
     }): Promise<{
         preservedRows: string[];
     }>;
     /**
      * Build the canonical `ExecuteActionRequest` shape the server
-     * expects (`script_name`, `script_version`, `function_name`, `input`,
+     * expects (`contract_id`, `contract_version`, `function_name`, `input`,
      * optional `pii_did`) and dispatch it through {@link execute}.
      *
      * Two pieces of glue live here that every typed user-contract
      * wrapper would otherwise duplicate:
      *
      * 1. **Field naming.** The server deserialises strictly into
-     *    `script_name` / `script_version` / `function_name` —
+     *    `contract_id` / `contract_version` / `function_name` —
      *    sending `contract` / `version` / `function` produces
      *    `Invalid action request: missing field …` 400s. Centralising
      *    the names here means every wrapper agrees with the server.
-     * 2. **`"latest"` resolution.** `script_version` is `SemVer` on
+     * 2. **`"latest"` resolution.** `contract_version` is `SemVer` on
      *    the server, so a literal `"latest"` cannot be parsed. We
      *    fetch the registered current version via
      *    `GET /api/contracts/current?name=…` (cached per script name
-     *    in `getScriptVersion`) and forward the resolved
+     *    in `getContractVersion`) and forward the resolved
      *    `MAJOR.MINOR.PATCH` string.
      *
      * Wrappers that need PII delegation can extend this helper
@@ -2599,876 +2968,497 @@ declare class T3nClient {
      *
      * **Security**: the contract only permits the merge when *both* DIDs
      * share a verified email or phone — i.e. the caller has OTP-proven
-     * ownership of the same contact on each side. An unproven email can
-     * never absorb a stranger's profile. Typical flow: authenticate
-     * (wallet) → {@link otpVerify} the email → read the returned
-     * `mergeSuggestion.existingDid` → call `mergeProfiles(existingDid)`.
-     *
-     * @param targetDid the surviving DID (absorbs the current session's
-     *   DID). Usually the `existingDid` from a {@link otpVerify}
-     *   `mergeSuggestion`.
-     * @throws {RpcError} if the contract refuses (e.g. the DIDs share no
-     *   verified contact) or on transport / decode failure.
-     */
-    mergeProfiles(targetDid: string): Promise<Record<string, unknown>>;
-    /**
-     * Submit Level-1 user-input fields to the slim
-     * `tee:user/contracts::user-upsert`. The contract merges the
-     * supplied profile fields, validates them, mints
-     * `t3n.user-input.kyc.1` once every Level-1 field is present, and
-     * commits the write.
-     *
-     * **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
-     * {@link UserUpsertError} `kind = "EmailNotVerified"`.
-     *
-     * Two recommended flows depending on how the session logged in:
-     * - **Email-OTP login** ({@link createEmailOtpAuthInput}): the
-     *   login already proved the email (and sent the only OTP email),
-     *   so call `submitUserInput` DIRECTLY — the gate passes on the
-     *   session authenticator and `verified_contacts.email` is
-     *   auto-stamped. Do NOT call {@link otpRequest} first; that sends
-     *   a redundant second OTP email.
-     * - **Wallet / OIDC login** (no proven email yet): "request OTP ->
-     *   verify OTP -> submit user input" (or use
-     *   {@link runOtpThenUserInput} which chains all three).
-     *
-     * The KYC webhook orphan-attestation flow stays here: when
-     * `requireExistingUser` is set, the contract identifies the user
-     * by DID (vendorData) instead of email and the gate is bypassed.
-     *
-     * @throws {UserUpsertError} when the contract returns a typed
-     *   error (`email_not_verified`, `legacy_field`, `user_not_found`).
-     *   Branch on `err.kind`.
-     * @throws {RpcError} for non-typed transport / decode failures.
-     */
-    submitUserInput(input: SubmitUserInputArgs): Promise<SubmitUserInputResult>;
-    /**
-     * Replace this user's agent-authorisation policy (`tee:user/contracts` →
-     * `agent-auth-update`). The supplied document IS the new state: an empty
-     * `agents` array revokes all agent access, and an omitted `discoverDids`
-     * persists an empty discovery-grant list. This is the full-document
-     * write — use {@link T3nClient.updateAgentAuth} for the single-grant
-     * read-merge-write that preserves other contracts' grants and the
-     * standing discovery grants.
-     *
-     * Typed wrapper over the raw contract call: callers pass camelCase input;
-     * the SDK emits the canonical snake_case wire via
-     * {@link toAgentAuthUpdateWire} (carrying `scopes` / `read_scopes` /
-     * validity alongside `functions` / `allowed_hosts`, plus the
-     * document-level `discover_dids`), so it does not rely on the contract's
-     * compatibility aliases.
-     *
-     * @throws {RpcError} if the contract rejects the policy (validation failure,
-     *   too many agents/grants).
-     */
-    agentAuthUpdate(input: AgentAuthUpdateInput): Promise<void>;
-    /**
-     * Convenience helper: run the explicit OTP roundtrip and submit
-     * the slim user-upsert in one call.
-     *
-     * The caller supplies a `getOtpCode(contact, channel)` callback
-     * the SDK invokes between request and verify — this is where
-     * a UI prompts the user to type the code that arrived on email
-     * / SMS. Throw from the callback to abort the flow; the helper
-     * does not retry on its own.
-     *
-     * Returns the slim `submitUserInput` result on success. Throws
-     * {@link UserUpsertError} or `RpcError` on the same conditions
-     * as the underlying wrappers.
-     *
-     * Optional, opt-in path — the recommended default is to call
-     * {@link otpRequest}, {@link otpVerify}, and
-     * {@link submitUserInput} explicitly so the application owns the
-     * flow.
-     *
-     * Do NOT use this for the email a session authenticated with via
-     * email-OTP login: it always runs {@link otpRequest},
-     * which dispatches a redundant second OTP email for an
-     * already-proven email. For an email-OTP login, call
-     * {@link submitUserInput} directly. This helper is for sessions
-     * that still need to prove the contact (phone, or an email on a
-     * wallet/OIDC session).
-     */
-    runOtpThenUserInput(args: {
-        channel: OtpChannel;
-        emailAddress?: string;
-        phoneNumber?: string;
-        profile: SubmitUserInputArgs["profile"];
-        organisationDid?: string;
-        attestations?: unknown;
-        keys?: Record<string, unknown>;
-        /**
-         * Testnet self-admit, propagated to the inner
-         * {@link submitUserInput} call. Inspect `result.tenantAdmit` for
-         * the outcome.
-         */
-        becomeDevTenant?: boolean;
-        getOtpCode: (contact: string, channel: OtpChannel) => Promise<string> | string;
-    }): Promise<SubmitUserInputResult>;
-    /**
-     * Poll `kyc-status` until a terminal status arrives or the
-     * configured timeout elapses.
-     *
-     * 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
-     * the slow window kicks in). [[KycStatusTimeoutError]] is thrown
-     * if the timeout elapses without reaching a terminal state.
-     *
-     * `opts.signal` cancels the loop synchronously — the helper
-     * stops sleeping and rejects with the abort reason; an
-     * already-in-flight `kycStatus()` request is allowed to settle
-     * but its result is discarded.
-     *
-     * `opts.onUpdate` fires once per snapshot, including
-     * intermediate `pending` ones. Errors thrown from the callback
-     * are swallowed so a misbehaving UI handler can't strand the
-     * poll loop.
-     *
-     * @throws [[KycStatusTimeoutError]] when the cadence's
-     *   `timeoutMs` elapses without a terminal status.
-     * @throws the abort reason when `opts.signal` is aborted.
-     * @throws the underlying RPC error when the contract or
-     *   transport raises (e.g. session expiry mid-poll).
-     */
-    kycStatusPoll(opts?: KycPollOptions): Promise<KycStatus>;
-    /**
-     * The server-minted session ID once handshake has completed, or
-     * `null` beforehand.
-     */
-    getSessionId(): SessionId | null;
-    getStatus(): SessionStatus;
-    getDid(): Did | null;
-    getLastSetCookie(): string | null;
-    getLastResponseHeaders(): Record<string, string>;
-    isAuthenticated(): boolean;
-    /**
-     * Run a WASM state machine flow to completion.
-     *
-     * Clears both `wasmState[method]` and `finalizedPayload[method]`
-     * at entry so a flow that previously threw partway (e.g. an RPC
-     * error) starts from a clean slate on retry. Without the reset,
-     * stale state from the failed attempt leaks into the new flow
-     * and `tryFinalize` may either spuriously succeed or run `next()`
-     * against a state that no longer matches the action we're sending.
-     *
-     * The `tryFinalize`-then-`next` order is load-bearing: the loop's
-     * exit condition fires *after* the previous iteration's
-     * `handleWasmRequest` has flushed the outbound peer reply, so
-     * every state-machine emission reaches the wire before we extract
-     * the final payload.
-     */
-    private runFlow;
-    /**
-     * Try to finalize the current flow. Returns the finish() payload
-     * (a serialized Session for handshake, a serialized DID for auth)
-     * or `null` if the state machine has not reached its terminal phase
-     * yet.
-     *
-     * The "not yet finalized" case is the loop's signal to keep
-     * iterating, not a real error. Any *other* failure must propagate
-     * so callers see real WASM errors instead of silent retries that
-     * spin forever.
-     *
-     * The terminal payload is stored in `finalizedPayload[method]`
-     * (a separate field from `wasmState[method]`) so the in-flight
-     * state-machine bytes and the finalized session/DID bytes never
-     * occupy the same slot. `getSessionState()` reads from
-     * `finalizedPayload.handshake`.
-     */
-    private tryFinalize;
-    /**
-     * Handle a WASM request based on its type
-     */
-    private handleWasmRequest;
-    /**
-     * Handle a send-remote request by calling the RPC endpoint
-     */
-    private handleSendRemote;
-    private captureHandshakeResult;
-    /**
-     * Handle a guest-to-host request using configured handlers
-     */
-    private handleGuestToHost;
-    /**
-     * Send an RPC request with automatic encryption/decryption
-     */
-    private sendRpcRequest;
-    /**
-     * Send a session-authenticated JSON-RPC request with plaintext
-     * params/result (no SessionEncryption layer). Used for tenant-facing
-     * read endpoints whose payloads carry only public / non-disclosive
-     * metadata (`contracts.list`, `delegation.check`) where the
-     * server-side handler reads the JSON envelope directly. (The token
-     * self-reads moved to the sealed path — see {@link getUsage}.)
+     * ownership of the same contact on each side. An unproven email can
+     * never absorb a stranger's profile. Typical flow: authenticate
+     * (wallet) → {@link otpVerify} the email → read the returned
+     * `mergeSuggestion.existingDid` → call `mergeProfiles(existingDid)`.
      *
-     * Auto-attaches the `Session-Id` header; surfaces JSON-RPC errors
-     * the same way as {@link sendRpcRequest} (typed
-     * `InsufficientCreditError` when applicable, `RpcError` otherwise).
-     * Returns the parsed `result` field — typically a JSON object the
-     * caller will narrow to the endpoint's response type.
+     * @param targetDid the surviving DID (absorbs the current session's
+     *   DID). Usually the `existingDid` from a {@link otpVerify}
+     *   `mergeSuggestion`.
+     * @throws {RpcError} if the contract refuses (e.g. the DIDs share no
+     *   verified contact) or on transport / decode failure.
      */
-    private sendUnencryptedSessionRpc;
+    mergeProfiles(targetDid: string): Promise<Record<string, unknown>>;
     /**
-     * Send a session-authenticated JSON-RPC request whose params/result
-     * are sealed with the same {@link SessionEncryption} layer
-     * `action.execute` uses — for read endpoints that return PII
-     * (`audit.get-mine`) and therefore must not travel plaintext over
-     * TLS. Unlike {@link sendRpcRequest}, this is not tied to the WASM
-     * client `Method` state machine: it takes the raw RPC method string
-     * and only does encrypt → send → decrypt.
+     * Submit Level-1 user-input fields to the slim
+     * `tee:user/contracts::user-upsert`. The contract merges the
+     * supplied profile fields, validates them, mints
+     * `t3n.user-input.kyc.1` once every Level-1 field is present, and
+     * commits the write.
      *
-     * Requires an established (>= Encrypted) session; returns the
-     * decrypted plaintext response string for the caller to `JSON.parse`.
-     */
-    private sendEncryptedSessionRpc;
-    /**
-     * Inspect a JSON-RPC response for an `error` field and throw the
-     * appropriate typed exception. No-op when `response.error` is
-     * absent. Shared by every RPC path so wire-shape changes in the
-     * server's error envelope (typed-error subclasses, request-id
-     * placement, detail formatting) only need to land in one place.
+     * **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
+     * {@link UserUpsertError} `kind = "EmailNotVerified"`.
      *
-     * 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`.
-     * Extract both so callers (and toasts that only render `.message`)
-     * get the real reason plus an id an operator can grep in the logs.
+     * Two recommended flows depending on how the session logged in:
+     * - **Email-OTP login** ({@link createEmailOtpAuthInput}): the
+     *   login already proved the email (and sent the only OTP email),
+     *   so call `submitUserInput` DIRECTLY — the gate passes on the
+     *   session authenticator and `verified_contacts.email` is
+     *   auto-stamped. Do NOT call {@link otpRequest} first; that sends
+     *   a redundant second OTP email.
+     * - **Wallet / OIDC login** (no proven email yet): "request OTP ->
+     *   verify OTP -> submit user input" (or use
+     *   {@link runOtpThenUserInput} which chains all three).
      *
-     * 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. The wire format is stable.
+     * The KYC webhook orphan-attestation flow stays here: when
+     * `requireExistingUser` is set, the contract identifies the user
+     * by DID (vendorData) instead of email and the gate is bypassed.
+     *
+     * @throws {UserUpsertError} when the contract returns a typed
+     *   error (`email_not_verified`, `legacy_field`, `user_not_found`).
+     *   Branch on `err.kind`.
+     * @throws {RpcError} for non-typed transport / decode failures.
      */
-    private throwIfRpcError;
-    private sendMultipartRpcRequest;
+    submitUserInput(input: SubmitUserInputArgs): Promise<SubmitUserInputResult>;
     /**
-     * Capture the server-minted `Session-Id` from the last handshake
-     * 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
-     * (none exist today, but the state-machine loop can iterate) do
-     * not overwrite an already-set value.
+     * Replace this user's agent-authorisation policy (`tee:authorisations/contracts`
+     * → `agent-auth-update`). The supplied document IS the new state: an empty
+     * `grants` array revokes all agent access, and an empty `discover_dids`
+     * persists an empty discovery-grant list. This is the full-document
+     * write — use {@link T3nClient.updateAgentAuth} for the single-grant
+     * read-merge-write that preserves other contracts' grants and the
+     * standing discovery grants.
+     *
+     * The {@link AgentAuthDoc} IS the snake_case wire shape — grant rows are
+     * {@link BoundGrant} verbatim — so the document passes straight through with
+     * no casing transform. Absent per-grant qualifiers (`version_req` /
+     * `read_scopes` / `allowed_hosts` / `window`) are simply unset on the object
+     * and so omitted from the JSON.
+     *
+     * @throws {RpcError} if the contract rejects the policy (validation failure,
+     *   too many agents/grants).
      */
-    private captureMintedSessionId;
+    agentAuthUpdate(input: AgentAuthDoc): Promise<void>;
     /**
-     * Get the finalized session blob (for `session.encrypt` calls).
-     * Populated by `tryFinalize` once the handshake state machine
-     * reaches its terminal phase.
-     */
-    private getSessionState;
-}
-
-/**
- * Guest-to-Host Request Handlers
- *
- * These handle requests from WASM that need the host environment to perform side effects.
- * Examples: signing challenges, providing public keys, generating random bytes.
- */
-
-/**
- * Account — MetaMask handler accepts either a plain address string or an
- * object with an `address` field (for compatibility with various wallet
- * libraries).
- */
-type EthAccount = string | {
-    address: string;
-};
-/**
- * Create an EthSign handler using MetaMask (window.ethereum)
- * @param account - MetaMask account (string address or object with address property)
- * @param logger - Optional logger instance. Defaults to a logger using the global log level (LogLevel.ERROR).
- *   Pass a custom logger to override logging behavior for this handler.
- * @param privateKey - Optional private key for signing (if provided, MetaMask is not used)
- */
-declare function metamask_sign(account: EthAccount, logger?: Logger, privateKey?: string | undefined): GuestToHostHandler;
-/**
- * Get the current MetaMask address
- * @returns Ethereum address (lowercase, 0x prefixed)
- */
-declare function metamask_get_address(): Promise<string>;
-/**
- * Get the address for a given private key
- * @param privateKey - Ethereum private key (0x prefixed hex string)
- * @returns Ethereum address (lowercase, 0x prefixed)
- */
-declare function eth_get_address(privateKey: string): string;
-/**
- * Create an MlKemPublicKey handler that lazily fetches the root public key
- * from `${baseUrl}/status` on first invocation, verifies it against the
- * DKG attestation trust anchor (SP-003), and caches the encoded response
- * for subsequent calls.
- *
- * @param baseUrl - **Required**. The node URL whose `/status` endpoint should
- *                  serve the ML-KEM public key. Must be the same URL the
- *                  T3nClient is constructed with — otherwise the handshake
- *                  encrypts to one node and sends ciphertext to another.
- *
- *                  Was optional in 0.3.x, where omitting it caused the lazy
- *                  fetch to silently fall back to `NODE_URLS[currentEnv]` and
- *                  hit the wrong node. Three downstream consumers (demo.ts,
- *                  t3-apps dev wallet hooks, t3n-mcp session manager) all
- *                  hit this trap before we tightened the type.
- * @param trustAnchor - **Required**. Client-pinned expected peer IDs +
- *                  RTMR3 allowlist the DKG bundle is verified against, or
- *                  `{ unsafe_trust_server: true }` to skip verification.
- *                  The key is only cached/returned once verification passes.
- */
-declare function createMlKemPublicKeyHandler(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandler;
-/**
- * Create Random handler backed by crypto.getRandomValues
- * Note: The Rust Vec<u8> type serializes as an array of bytes, not a base64 string
- */
-declare function createRandomHandler(): GuestToHostHandler;
-/**
- * Create the default handler set required by the T3n handshake.
- *
- * @param baseUrl - **Required**. Forwarded to `createMlKemPublicKeyHandler`
- *                  so the lazy /status fetch hits the right node.
- * @param trustAnchor - **Required**. Forwarded to the ML-KEM handler so the
- *                  fetched key is verified against the DKG attestation
- *                  (SP-003) before the handshake trusts it.
- */
-declare function createDefaultHandlers(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandlers;
-
-/**
- * Stateless `api_key` agent auth.
- *
- * `invoke` posts once to `POST /api/invoke` — an HTTPS-only
- * endpoint (see the HTTPS-guard note below) that authenticates an org agent
- * by an opaque API key (`X-T3N-Api-Key: t3n_key_<...>`) and executes a
- * `z:` contract as that agent in the SAME request. Unlike
- * {@link T3nClient.execute}, there is **no** ML-KEM handshake, **no**
- * `Session-Id`, and **no** session state: the node derives the acting agent
- * DID from the relayed key per-call (`resolve_stateless_credential`
- * driving the session contract's `api_key` action), then runs the same
- * execute pipeline `action.execute` runs after `check_authentication`
- * (`ActionService::execute_as_did`), and returns the contract's decoded
- * result as a plain `Json(result)` body — NOT a JSON-RPC envelope.
- *
- * Because the response is the bare decoded value (no `{jsonrpc,result,id}`
- * wrapper to unwrap), decoding reuses {@link parseContractResponse} — the
- * exact same JSON.parse + optional-schema path {@link T3nClient.executeAndDecode}
- * uses for the session `execute` RPC — so callers get identical typed /
- * schema-validated decoding on either path.
- *
- * This module intentionally does NOT import {@link T3nClient}, the WASM
- * component loader, or any handshake/session machinery — `invoke` is
- * a single fetch, nothing else.
- *
- * ### HTTPS guard (CodeRabbit T2)
- * The API key is a long-lived bearer credential relayed in a plain header,
- * so `invoke` refuses to send it over an insecure transport: `baseUrl`
- * must be `https:`, unless the host is a local-dev loopback
- * (`localhost` / `127.0.0.1` / `[::1]`), in which case plain `http:` is
- * allowed. The check runs before any network activity — an insecure
- * `baseUrl` never gets as far as a `fetch` call.
- *
- * ### Error hygiene (CodeRabbit T3/T4/T5)
- * Every error `invoke` throws is a fixed, generic
- * {@link InvokeError} message — the response body text, the
- * underlying network error's message, and the api key are never
- * interpolated into it. This is defense in depth against a server (or a
- * malicious intermediary) that echoes the key or other secrets back in an
- * error body: whatever comes back over the wire on a non-2xx response is
- * discarded, not surfaced. The timeout timer also stays armed until the
- * response body has been fully read (or has itself timed out) — see
- * {@link invoke}'s implementation — so a connection that delivers
- * headers and then stalls on the body still respects `timeoutMs`.
- */
-
-/**
- * Wire body for `POST /api/invoke` — mirrors the server's
- * server-side `ExecuteActionRequest`, the same shape
- * `T3nClient`'s `execute*` wrappers build for the session `action.execute`
- * RPC. Field names are load-bearing: the server deserialises strictly into
- * `script_name` / `script_version` / `function_name` (see
- * `T3nClient.executeSystemContract`'s doc comment) — `contract` / `version`
- * / `function` produce a 400.
- */
-interface InvokeRequest {
-    script_name: string;
-    script_version: string;
-    function_name: string;
-    /** Delegated-call target member; omitted for a self (non-delegated) call. */
-    pii_did?: string;
-    input?: unknown;
-}
-/** Options for {@link invoke}. */
-interface InvokeOptions {
+     * Convenience helper: run the explicit OTP roundtrip and submit
+     * the slim user-upsert in one call.
+     *
+     * The caller supplies a `getOtpCode(contact, channel)` callback
+     * the SDK invokes between request and verify — this is where
+     * a UI prompts the user to type the code that arrived on email
+     * / SMS. Throw from the callback to abort the flow; the helper
+     * does not retry on its own.
+     *
+     * Returns the slim `submitUserInput` result on success. Throws
+     * {@link UserUpsertError} or `RpcError` on the same conditions
+     * as the underlying wrappers.
+     *
+     * Optional, opt-in path — the recommended default is to call
+     * {@link otpRequest}, {@link otpVerify}, and
+     * {@link submitUserInput} explicitly so the application owns the
+     * flow.
+     *
+     * Do NOT use this for the email a session authenticated with via
+     * email-OTP login: it always runs {@link otpRequest},
+     * which dispatches a redundant second OTP email for an
+     * already-proven email. For an email-OTP login, call
+     * {@link submitUserInput} directly. This helper is for sessions
+     * that still need to prove the contact (phone, or an email on a
+     * wallet/OIDC session).
+     */
+    runOtpThenUserInput(args: {
+        channel: OtpChannel;
+        emailAddress?: string;
+        phoneNumber?: string;
+        profile: SubmitUserInputArgs["profile"];
+        organisationDid?: string;
+        attestations?: unknown;
+        keys?: Record<string, unknown>;
+        /**
+         * Testnet self-admit, propagated to the inner
+         * {@link submitUserInput} call. Inspect `result.tenantAdmit` for
+         * the outcome.
+         */
+        becomeDevTenant?: boolean;
+        getOtpCode: (contact: string, channel: OtpChannel) => Promise<string> | string;
+    }): Promise<SubmitUserInputResult>;
     /**
-     * RPC base URL of the T3n node, e.g. `https://node.example.com`. Must be
-     * `https:` unless the host is a local-dev loopback (`localhost` /
-     * `127.0.0.1` / `[::1]`) — see the module doc comment's HTTPS-guard note.
+     * Poll `kyc-status` until a terminal status arrives or the
+     * configured timeout elapses.
+     *
+     * 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
+     * the slow window kicks in). [[KycStatusTimeoutError]] is thrown
+     * if the timeout elapses without reaching a terminal state.
+     *
+     * `opts.signal` cancels the loop synchronously — the helper
+     * stops sleeping and rejects with the abort reason; an
+     * already-in-flight `kycStatus()` request is allowed to settle
+     * but its result is discarded.
+     *
+     * `opts.onUpdate` fires once per snapshot, including
+     * intermediate `pending` ones. Errors thrown from the callback
+     * are swallowed so a misbehaving UI handler can't strand the
+     * poll loop.
+     *
+     * @throws [[KycStatusTimeoutError]] when the cadence's
+     *   `timeoutMs` elapses without a terminal status.
+     * @throws the abort reason when `opts.signal` is aborted.
+     * @throws the underlying RPC error when the contract or
+     *   transport raises (e.g. session expiry mid-poll).
      */
-    baseUrl: string;
+    kycStatusPoll(opts?: KycPollOptions): Promise<KycStatus>;
     /**
-     * The agent's opaque API key (`t3n_key_<...>`), relayed verbatim in the
-     * `X-T3N-Api-Key` header. Never logged and never interpolated into any
-     * error this module throws — see the module doc comment and
-     * {@link InvokeError}.
+     * The server-minted session ID once handshake has completed, or
+     * `null` beforehand.
      */
-    apiKey: string;
-    /** The wire request to execute, built to the {@link InvokeRequest} shape. */
-    request: InvokeRequest;
-    /** Fetch timeout in ms. Defaults to 30s, matching {@link HttpTransport}. */
-    timeoutMs?: number;
-}
-/**
- * Thrown when `POST /api/invoke` fails at the transport or HTTP
- * layer (network failure, timeout, non-2xx status). Contract-level errors
- * the node returns as a 2xx JSON error value are NOT wrapped here — they
- * flow through {@link parseContractResponse}'s normal return, same as the
- * session `execute` path.
- *
- * The message is always one of a small set of fixed, generic strings — it
- * NEVER contains the raw api key, the response body text, or the
- * underlying network error's message (CodeRabbit T4/T5): a server (or a
- * misbehaving intermediary) that echoes the key or other secrets back in
- * an error body must not be able to leak them through this error's
- * message.
- */
-declare class InvokeError extends T3nError {
-    readonly status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
-}
-/**
- * Execute a `z:` contract as an org agent, authenticating with an opaque
- * API key — one request, no handshake, no session.
- *
- * @param opts - baseUrl, apiKey, and the wire request to execute
- * @param schema - optional validator applied to the decoded result (e.g. a
- *   zod schema); anything exposing `.parse(value)` is accepted, same as
- *   {@link T3nClient.executeAndDecode}
- * @returns the contract's decoded result, typed as `T`
- * @throws {InvokeError} if `baseUrl` is insecure, on a network
- *   failure/timeout, or on a non-2xx response
- * @throws {ContractResponseError} if the node returns a 2xx with a body
- *   that is not valid JSON
- */
-declare function invoke<T = unknown>(opts: InvokeOptions, schema?: ContractResponseSchema<T>): Promise<T>;
-
-/**
- * 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.
- *
- * 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;
-/**
- * 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 function formatTokens(baseUnits: number | bigint): string;
-/**
- * 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[];
-}
-/**
- * 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;
+    getSessionId(): SessionId | null;
+    getStatus(): SessionStatus;
+    getDid(): Did | null;
+    getLastSetCookie(): string | null;
+    getLastResponseHeaders(): Record<string, string>;
+    isAuthenticated(): boolean;
     /**
-     * Per-org ceiling on delegation-credential validity (seconds).
+     * Run a WASM state machine flow to completion.
+     *
+     * Clears both `wasmState[method]` and `finalizedPayload[method]`
+     * at entry so a flow that previously threw partway (e.g. an RPC
+     * error) starts from a clean slate on retry. Without the reset,
+     * stale state from the failed attempt leaks into the new flow
+     * and `tryFinalize` may either spuriously succeed or run `next()`
+     * against a state that no longer matches the action we're sending.
+     *
+     * The `tryFinalize`-then-`next` order is load-bearing: the loop's
+     * exit condition fires *after* the previous iteration's
+     * `handleWasmRequest` has flushed the outbound peer reply, so
+     * every state-machine emission reaches the wire before we extract
+     * the final payload.
+     */
+    private runFlow;
+    /**
+     * Try to finalize the current flow. Returns the finish() payload
+     * (a serialized Session for handshake, a serialized DID for auth)
+     * or `null` if the state machine has not reached its terminal phase
+     * yet.
+     *
+     * The "not yet finalized" case is the loop's signal to keep
+     * iterating, not a real error. Any *other* failure must propagate
+     * so callers see real WASM errors instead of silent retries that
+     * spin forever.
+     *
+     * The terminal payload is stored in `finalizedPayload[method]`
+     * (a separate field from `wasmState[method]`) so the in-flight
+     * state-machine bytes and the finalized session/DID bytes never
+     * occupy the same slot. `getSessionState()` reads from
+     * `finalizedPayload.handshake`.
+     */
+    private tryFinalize;
+    /**
+     * Handle a WASM request based on its type
+     */
+    private handleWasmRequest;
+    /**
+     * Handle a send-remote request by calling the RPC endpoint
+     */
+    private handleSendRemote;
+    private captureHandshakeResult;
+    /**
+     * Handle a guest-to-host request using configured handlers
+     */
+    private handleGuestToHost;
+    /**
+     * Send an RPC request with automatic encryption/decryption
+     */
+    private sendRpcRequest;
+    /**
+     * Send a session-authenticated JSON-RPC request with plaintext
+     * params/result (no SessionEncryption layer). Used for tenant-facing
+     * read endpoints whose payloads carry only public / non-disclosive
+     * metadata (`contracts.list`, `delegation.check`) where the
+     * server-side handler reads the JSON envelope directly. (The token
+     * self-reads moved to the sealed path — see {@link getUsage}.)
+     *
+     * Auto-attaches the `Session-Id` header; surfaces JSON-RPC errors
+     * the same way as {@link sendRpcRequest} (typed
+     * `InsufficientCreditError` when applicable, `RpcError` otherwise).
+     * Returns the parsed `result` field — typically a JSON object the
+     * caller will narrow to the endpoint's response type.
+     */
+    private sendUnencryptedSessionRpc;
+    /**
+     * Send a session-authenticated JSON-RPC request whose params/result
+     * are sealed with the same {@link SessionEncryption} layer
+     * `action.execute` uses — for read endpoints that return PII
+     * (`audit.get-mine`) and therefore must not travel plaintext over
+     * TLS. Unlike {@link sendRpcRequest}, this is not tied to the WASM
+     * client `Method` state machine: it takes the raw RPC method string
+     * and only does encrypt → send → decrypt.
+     *
+     * Requires an established (>= Encrypted) session; returns the
+     * decrypted plaintext response string for the caller to `JSON.parse`.
+     */
+    private sendEncryptedSessionRpc;
+    /**
+     * Inspect a JSON-RPC response for an `error` field and throw the
+     * appropriate typed exception. No-op when `response.error` is
+     * absent. Shared by every RPC path so wire-shape changes in the
+     * server's error envelope (typed-error subclasses, request-id
+     * placement, detail formatting) only need to land in one place.
      *
-     * 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)`.
+     * 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`.
+     * Extract both so callers (and toasts that only render `.message`)
+     * get the real reason plus an id an operator can grep in the logs.
+     *
+     * 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. The wire format is stable.
      */
-    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 {
+    private throwIfRpcError;
+    private sendMultipartRpcRequest;
     /**
-     * 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`).
+     * Capture the server-minted `Session-Id` from the last handshake
+     * 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
+     * (none exist today, but the state-machine loop can iterate) do
+     * not overwrite an already-set value.
      */
-    effective_validity_secs: number;
-}
-/** Shallow runtime guard for {@link OrgPolicyView}. */
-declare function isOrgPolicyView(value: unknown): value is OrgPolicyView;
-/**
- * Caller-scoped admin status returned by `org-am-i-admin`.
- *
- * Reports only whether the **calling** session's DID is in the org's admin
- * list — never the roster itself (contrast {@link OrgPolicyMeta}, returned by
- * the admin-gated `org-policy-get`). Readable by any authenticated session.
- * Mirrors the org-data `AmIAdminResponse` wire shape.
- */
-interface OrgAdminStatus {
-    /** Whether the calling session is an admin of the queried org. */
-    is_admin: boolean;
-}
-/** Shallow runtime guard for {@link OrgAdminStatus}. */
-declare function isOrgAdminStatus(value: unknown): value is OrgAdminStatus;
-/**
- * Standard response returned by all policy write and data mutation operations.
- *
- * Mirrors the org-data `MutationResponse` wire shape.
- */
-interface MutationResponse {
+    private captureMintedSessionId;
     /**
-     * `"created"`, `"updated"`, `"deleted"`, or — for the agent-card mutations —
-     * `"published"` / `"unpublished"`.
+     * Get the finalized session blob (for `session.encrypt` calls).
+     * Populated by `tryFinalize` once the handshake state machine
+     * reaches its terminal phase.
      */
-    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;
+    private getSessionState;
 }
+
 /**
- * Shallow runtime guard for {@link MutationResponse}.
+ * Guest-to-Host Request Handlers
  *
- * 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.
+ * These handle requests from WASM that need the host environment to perform side effects.
+ * Examples: signing challenges, providing public keys, generating random bytes.
  */
-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>`.
+ * Account — MetaMask handler accepts either a plain address string or an
+ * object with an `address` field (for compatibility with various wallet
+ * libraries).
  */
-interface OrgWriters {
-    writers: string[];
-}
-/** Shallow runtime guard for {@link OrgWriters}. */
-declare function isOrgWriters(value: unknown): value is OrgWriters;
+type EthAccount = string | {
+    address: string;
+};
 /**
- * Response type alias for org-grants-get.
- *
- * The wire body echoes the `contract_id` alongside the grant list.
+ * Create an EthSign handler using MetaMask (window.ethereum)
+ * @param account - MetaMask account (string address or object with address property)
+ * @param logger - Optional logger instance. Defaults to a logger using the global log level (LogLevel.ERROR).
+ *   Pass a custom logger to override logging behavior for this handler.
+ * @param privateKey - Optional private key for signing (if provided, MetaMask is not used)
  */
-interface OrgContractGrants {
-    contract_id: string;
-    grants: UserGrant[];
-}
+declare function metamask_sign(account: EthAccount, logger?: Logger, privateKey?: string | undefined): GuestToHostHandler;
 /**
- * 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.
+ * Get the current MetaMask address
+ * @returns Ethereum address (lowercase, 0x prefixed)
  */
-declare function isOrgContractGrants(value: unknown): value is OrgContractGrants;
+declare function metamask_get_address(): Promise<string>;
 /**
- * One grant inside a role: a {@link UserGrant} body (without the
- * grantee, which is bound at assignment time) plus the target contract.
- * Mirrors the org-data `RoleGrant` wire shape.
+ * Get the address for a given private key
+ * @param privateKey - Ethereum private key (0x prefixed hex string)
+ * @returns Ethereum address (lowercase, 0x prefixed)
  */
-interface RoleGrant {
-    /** Target contract (canonical name, e.g. `"tee:z-payroll/contracts"`). */
-    contract_id: string;
-    /** WIT function names this grant confers. */
-    functions: string[];
-    /** Data scope paths this grant confers (canonicalised lowercase). */
-    scopes: string[];
-}
+declare function eth_get_address(privateKey: string): string;
 /**
- * A role: a named bundle of grants and/or composed sub-roles.
- * Mirrors the org-data `RoleDefinition` wire shape.
+ * Create an MlKemPublicKey handler that lazily fetches the root public key
+ * from `${baseUrl}/status` on first invocation, verifies it against the
+ * DKG attestation trust anchor (SP-003), and caches the encoded response
+ * for subsequent calls.
+ *
+ * @param baseUrl - **Required**. The node URL whose `/status` endpoint should
+ *                  serve the ML-KEM public key. Must be the same URL the
+ *                  T3nClient is constructed with — otherwise the handshake
+ *                  encrypts to one node and sends ciphertext to another.
+ *
+ *                  Was optional in 0.3.x, where omitting it caused the lazy
+ *                  fetch to silently fall back to `NODE_URLS[currentEnv]` and
+ *                  hit the wrong node. Three downstream consumers (demo.ts,
+ *                  t3-apps dev wallet hooks, t3n-mcp session manager) all
+ *                  hit this trap before we tightened the type.
+ * @param trustAnchor - **Required**. Client-pinned expected peer IDs +
+ *                  RTMR3 allowlist the DKG bundle is verified against, or
+ *                  `{ unsafe_trust_server: true }` to skip verification.
+ *                  The key is only cached/returned once verification passes.
  */
-interface RoleDefinition {
-    /** Org-unique role identifier (slug; function-name grammar). */
-    role_id: string;
-    /** Human-facing label. */
-    label: string;
-    /** Composite: other role ids in the same org whose grants this role confers. */
-    includes: string[];
-    /** Grants this role confers directly. */
-    grants: RoleGrant[];
-}
+declare function createMlKemPublicKeyHandler(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandler;
 /**
- * The roles assigned to one grantee within one org.
- * Mirrors the org-data `RoleAssignments` wire shape.
+ * Create Random handler backed by crypto.getRandomValues
+ * Note: The Rust Vec<u8> type serializes as an array of bytes, not a base64 string
  */
-interface RoleAssignments {
-    /** Assigned role ids. */
-    roles: string[];
-}
-/** Response for `org-role-get`; `role` is `null` when the id is unknown. */
-interface RoleGetResponse {
-    role: RoleDefinition | null;
-}
-/** Shallow runtime guard for {@link RoleGetResponse}. */
-declare function isRoleGetResponse(value: unknown): value is RoleGetResponse;
-/** Response for `org-role-assignments-get`. */
-interface RoleAssignmentsResponse {
-    /** Echoed back so callers don't need to track which request this answers. */
-    grantee_did: string;
-    /** The grantee's assigned role ids (empty when none). */
-    roles: string[];
-}
-/** Shallow runtime guard for {@link RoleAssignmentsResponse}. */
-declare function isRoleAssignmentsResponse(value: unknown): value is RoleAssignmentsResponse;
+declare function createRandomHandler(): GuestToHostHandler;
 /**
- * Input for `listAgents` — the org plus optional pagination. Omit both `cursor`
- * and `limit` for the first page at the default limit; pass a previous
- * response's `next_cursor` back as `cursor` to fetch the following page.
+ * Create the default handler set required by the T3n handshake.
+ *
+ * @param baseUrl - **Required**. Forwarded to `createMlKemPublicKeyHandler`
+ *                  so the lazy /status fetch hits the right node.
+ * @param trustAnchor - **Required**. Forwarded to the ML-KEM handler so the
+ *                  fetched key is verified against the DKG attestation
+ *                  (SP-003) before the handshake trusts it.
  */
-interface ListAgentsInput {
-    orgDid: string;
-    /** Opaque cursor from a previous response's `next_cursor`. */
-    cursor?: string;
-    /** Maximum agents to return in this page. */
-    limit?: number;
-}
+declare function createDefaultHandlers(baseUrl: string, trustAnchor: TrustAnchorOrUnsafe): GuestToHostHandlers;
+
 /**
- * One org-owned agent in a {@link ListAgentsResponse}: the agent's DID, its
- * display name, and the number of distinct contracts it can access via a direct
- * grant. Mirrors the org-data `AgentSummary` wire shape. The name comes from the
- * agent's private card (falling back to the DID), so the FE no longer needs to
- * fetch each `public:agent_cards` entry to render the roster.
+ * Stateless `api_key` agent auth.
+ *
+ * `invoke` posts once to `POST /api/invoke` — an HTTPS-only
+ * endpoint (see the HTTPS-guard note below) that authenticates an org agent
+ * by an opaque API key (`X-T3N-Api-Key: t3n_key_<...>`) and executes a
+ * `z:` contract as that agent in the SAME request. Unlike
+ * {@link T3nClient.execute}, there is **no** ML-KEM handshake, **no**
+ * `Session-Id`, and **no** session state: the node derives the acting agent
+ * DID from the relayed key per-call (`resolve_stateless_credential`
+ * driving the session contract's `api_key` action), then runs the same
+ * execute pipeline `action.execute` runs after `check_authentication`
+ * (`ActionService::execute_as_did`), and returns the contract's decoded
+ * result as a plain `Json(result)` body — NOT a JSON-RPC envelope.
+ *
+ * Because the response is the bare decoded value (no `{jsonrpc,result,id}`
+ * wrapper to unwrap), decoding reuses {@link parseContractResponse} — the
+ * exact same JSON.parse + optional-schema path {@link T3nClient.executeAndDecode}
+ * uses for the session `execute` RPC — so callers get identical typed /
+ * schema-validated decoding on either path.
+ *
+ * This module intentionally does NOT import {@link T3nClient}, the WASM
+ * component loader, or any handshake/session machinery — `invoke` is
+ * a single fetch, nothing else.
+ *
+ * ### HTTPS guard (CodeRabbit T2)
+ * The API key is a long-lived bearer credential relayed in a plain header,
+ * so `invoke` refuses to send it over an insecure transport: `baseUrl`
+ * must be `https:`, unless the host is a local-dev loopback
+ * (`localhost` / `127.0.0.1` / `[::1]`), in which case plain `http:` is
+ * allowed. The check runs before any network activity — an insecure
+ * `baseUrl` never gets as far as a `fetch` call.
+ *
+ * ### Error hygiene (CodeRabbit T3/T4/T5)
+ * Every error `invoke` throws is a fixed, generic
+ * {@link InvokeError} message — the response body text, the
+ * underlying network error's message, and the api key are never
+ * interpolated into it. This is defense in depth against a server (or a
+ * malicious intermediary) that echoes the key or other secrets back in an
+ * error body: whatever comes back over the wire on a non-2xx response is
+ * discarded, not surfaced. The timeout timer also stays armed until the
+ * response body has been fully read (or has itself timed out) — see
+ * {@link invoke}'s implementation — so a connection that delivers
+ * headers and then stalls on the body still respects `timeoutMs`.
  */
-interface AgentSummary {
-    /** The agent's DID (`did:t3n:<40-hex>`). */
-    did: string;
-    /** The agent's display name, from its private card (DID when unavailable). */
-    name: string;
-    /** Count of distinct contracts the agent holds a direct grant on. */
-    contract_count: number;
-}
-/** Response for `org-data-list-agents`. */
-interface ListAgentsResponse {
-    /** One PAGE of the org's org-owned agents, sorted by DID. */
-    agents: AgentSummary[];
-    /** Opaque cursor for the next page; absent on the last page. */
-    next_cursor?: string;
-}
-/** A human member's org role. The closed wire domain of {@link HumanMember}. */
-type MemberRole = "admin" | "member";
+
 /**
- * Input for `listHumanMembers` — the org plus optional pagination. Omit both
- * `cursor` and `limit` for the first page at the default limit; pass a previous
- * response's `next_cursor` back as `cursor` to fetch the following page.
+ * Wire body for `POST /api/invoke` — mirrors the server's
+ * server-side `ExecuteActionRequest`, the same shape
+ * `T3nClient`'s `execute*` wrappers build for the session `action.execute`
+ * RPC. Field names are load-bearing: the server deserialises strictly into
+ * `contract_id` / `contract_version` / `function_name` (see
+ * `T3nClient.executeSystemContract`'s doc comment) — `contract` / `version`
+ * / `function` produce a 400.
  */
-interface ListHumanMembersInput {
-    orgDid: string;
-    /** Opaque cursor from a previous response's `next_cursor`. */
-    cursor?: string;
-    /** Maximum members to return in this page. */
-    limit?: number;
+interface InvokeRequest {
+    contract_id: string;
+    contract_version: string;
+    function_name: string;
+    /** Delegated-call target member; omitted for a self (non-delegated) call. */
+    pii_did?: string;
+    input?: unknown;
+}
+/** Options for {@link invoke}. */
+interface InvokeOptions {
+    /**
+     * RPC base URL of the T3n node, e.g. `https://node.example.com`. Must be
+     * `https:` unless the host is a local-dev loopback (`localhost` /
+     * `127.0.0.1` / `[::1]`) — see the module doc comment's HTTPS-guard note.
+     */
+    baseUrl: string;
+    /**
+     * The agent's opaque API key (`t3n_key_<...>`), relayed verbatim in the
+     * `X-T3N-Api-Key` header. Never logged and never interpolated into any
+     * error this module throws — see the module doc comment and
+     * {@link InvokeError}.
+     */
+    apiKey: string;
+    /** The wire request to execute, built to the {@link InvokeRequest} shape. */
+    request: InvokeRequest;
+    /** Fetch timeout in ms. Defaults to 30s, matching {@link HttpTransport}. */
+    timeoutMs?: number;
 }
 /**
- * One direct human member: DID plus org role. No profile PII (name/email are
- * out of scope and owned by `tee:user`). Mirrors the org-data `HumanMember`
- * wire shape.
+ * Thrown when `POST /api/invoke` fails at the transport or HTTP
+ * layer (network failure, timeout, non-2xx status). Contract-level errors
+ * the node returns as a 2xx JSON error value are NOT wrapped here — they
+ * flow through {@link parseContractResponse}'s normal return, same as the
+ * session `execute` path.
+ *
+ * The message is always one of a small set of fixed, generic strings — it
+ * NEVER contains the raw api key, the response body text, or the
+ * underlying network error's message (CodeRabbit T4/T5): a server (or a
+ * misbehaving intermediary) that echoes the key or other secrets back in
+ * an error body must not be able to leak them through this error's
+ * message.
  */
-interface HumanMember {
-    /** The member's DID (`did:t3n:<40-hex>`). */
-    did: string;
-    /** The member's org role. */
-    role: MemberRole;
-}
-/** Response for `org-data-list-human-members`. */
-interface ListHumanMembersResponse {
-    /** One PAGE of the org's direct human members, sorted by DID. */
-    members: HumanMember[];
-    /** Opaque cursor for the next page; absent on the last page. */
-    next_cursor?: string;
-}
-/** Shallow runtime guard for {@link ListHumanMembersResponse}. */
-declare function isListHumanMembersResponse(value: unknown): value is ListHumanMembersResponse;
-/** Shallow runtime guard for {@link ListAgentsResponse}. */
-declare function isListAgentsResponse(value: unknown): value is ListAgentsResponse;
-/** 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;
-/** Secret shape discriminator (mirrors the contract `SecretKind`). */
-type SecretKind = "single_value" | "json";
-/** Metadata common to every {@link SecretView} entry. */
-interface SecretViewBase {
-    /** Secret name (the `(org, name)` key tail). */
-    name: string;
-    /** Monotonic version, bumped on each value rotation and ACL edit. */
-    version: number;
-    /** Unix seconds of the most recent write. */
-    updated_at_secs: number;
+declare class InvokeError extends T3nError {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
 }
 /**
- * The redacted per-secret summary `org-secret-list` returns — a discriminated
- * union on `kind`. The value is NEVER present: a single-value exposes only its
- * last four characters and a json secret only its sorted top-level field names.
+ * Execute a `z:` contract as an org agent, authenticating with an opaque
+ * API key — one request, no handshake, no session.
+ *
+ * @param opts - baseUrl, apiKey, and the wire request to execute
+ * @param schema - optional validator applied to the decoded result (e.g. a
+ *   zod schema); anything exposing `.parse(value)` is accepted, same as
+ *   {@link T3nClient.executeAndDecode}
+ * @returns the contract's decoded result, typed as `T`
+ * @throws {InvokeError} if `baseUrl` is insecure, on a network
+ *   failure/timeout, or on a non-2xx response
+ * @throws {ContractResponseError} if the node returns a 2xx with a body
+ *   that is not valid JSON
  */
-type SecretView = (SecretViewBase & {
-    kind: "single_value";
-    /** Last four characters of the value (whole value when ≤ 4 chars). */
-    last4: string;
-}) | (SecretViewBase & {
-    kind: "json";
-    /** Sorted top-level object field names (keys only, no values). */
-    field_names: string[];
-});
-/** Shallow runtime guard for {@link SecretView}. */
-declare function isSecretView(value: unknown): value is SecretView;
+declare function invoke<T = unknown>(opts: InvokeOptions, schema?: ContractResponseSchema<T>): Promise<T>;
+
 /**
- * Full secret record returned by `org-secret-get` — the value IS included
- * (the deliberate read-back path the READ axis exists for), along with all
- * three ACLs.
+ * 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.
+ *
+ * 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}.
  */
-interface SecretRecord {
-    name: string;
-    kind: SecretKind;
-    /** The value as text: the scalar for a single-value, canonical JSON object for a json secret. */
-    value: string;
-    version: number;
-    /** READ axis — DIDs allowed to read the value back. */
-    reader_dids: string[];
-    /** READ axis — role ids allowed to read the value back. */
-    reader_roles: string[];
-    /** MANAGE axis — DIDs allowed to rotate the value. */
-    manager_dids: string[];
-    /** MANAGE axis — role ids allowed to rotate the value. */
-    manager_roles: string[];
-    /** USE axis — canonical contract ids allowed to have the value injected. */
-    contract_allowlist: string[];
-    created_at_secs: number;
-    updated_at_secs: number;
-    /** DID of the caller who last wrote the record. */
-    updated_by: string;
-}
-/** Shallow runtime guard for {@link SecretRecord}. */
-declare function isSecretRecord(value: unknown): value is SecretRecord;
-/** Response for `org-secret-list`: redacted per-kind views, no values. */
-interface SecretListResponse {
-    secrets: SecretView[];
-}
-/** Shallow runtime guard for {@link SecretListResponse}. */
-declare function isSecretListResponse(value: unknown): value is SecretListResponse;
-/** 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;
+/** 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;
 /**
- * Return shape of `agentCardGet` — composed client-side from the generic
- * `org-data-get` read of the card's entry (there is no card-specific read
- * operation on the contract). To check whether a public copy exists, probe
- * the anonymous `GET /api/agent-card/{did}` endpoint.
+ * 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`.
  */
-interface AgentCardResponse {
-    /** The agent whose card this is (`did:t3n:<40-hex>`). */
-    agent_did: string;
-    /** The stored card JSON body, verbatim. */
-    card: string;
-}
-/** Shallow runtime guard for {@link AgentCardResponse}. */
-declare function isAgentCardResponse(value: unknown): value is AgentCardResponse;
+declare function formatTokens(baseUnits: number | bigint): string;
 /**
- * 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.
+ * 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`.
  */
-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 function toBaseUnits(tokens: number): number;
 
 /**
  * OrgDataClient — typed wrapper over the existing authenticated
@@ -3541,10 +3531,17 @@ interface SetWritersInput {
     scope: string;
     writers: string[];
 }
+/**
+ * A grant to set via {@link OrgDataClient.setGrants}. The per-grant
+ * `contract_id` is injected by the SDK from the request `contractId` (the
+ * contract sets it server-side regardless), so callers omit it — a read-back
+ * {@link BoundGrant}, which carries `contract_id`, is still assignable.
+ */
+type SetGrantInput = Omit<BoundGrant, "contract_id">;
 interface SetGrantsInput {
     orgDid: string;
     contractId: string;
-    grants: UserGrant[];
+    grants: SetGrantInput[];
 }
 interface DeleteGrantsInput {
     orgDid: string;
@@ -3806,7 +3803,7 @@ declare class OrgDataClient {
     /** Delete a secret entirely (org-admin only). */
     secretDelete(input: SecretNameInput): Promise<MutationResponse>;
     /**
-     * Full replacement of the user-grant list for a contract.
+     * Full replacement of the org's grant list for a contract.
      *
      * Passing an empty list removes the entry.
      */
@@ -3885,7 +3882,7 @@ declare class OrgDataClient {
     purgeOrg(input: PurgeOrgInput): Promise<MutationResponse>;
     /**
      * Detach-cascade grant sweep: drop `memberDid` from every
-     * one of the org's per-contract `UserGrant` lists. Authorised for an
+     * one of the org's per-contract `BoundGrant` lists. Authorised for an
      * org-admin of the subject, or the member removing their own grants.
      * `deleted_entries` reports how many contract grant lists were rewritten.
      */
@@ -4083,7 +4080,7 @@ declare function createOrgDataClientFromSession(t3n: T3nClient, baseUrl: string)
  *
  * 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
+ * `agent_auth` ∩ `org_grant` 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.
@@ -4302,7 +4299,7 @@ declare function stringToBytes(str: string): Uint8Array;
  */
 declare function bytesToString(bytes: Uint8Array): string;
 
-declare function getScriptVersion(rpcUrl: string, scriptName: string): Promise<string>;
+declare function getContractVersion(rpcUrl: string, contractId: string): Promise<string>;
 
 /**
  * Secret redaction utilities for T3n SDK
@@ -4344,7 +4341,7 @@ declare function redactSecretsFromJson(jsonString: string): string;
  *
  * Predicates are intentionally shallow — they validate the immediate
  * top-level structure (object kind, presence/type of leading fields)
- * but do not deeply validate nested elements (e.g. each `UserGrant`
+ * but do not deeply validate nested elements (e.g. each `BoundGrant`
  * inside `OrgContractGrants.grants`). Deep validation would be brittle
  * against benign contract additions; shallow guards catch the failure
  * modes that actually surface as runtime crashes (null/string/missing
@@ -4625,7 +4622,7 @@ interface TenantBaseClient {
 }
 interface TenantClientConfig {
     environment?: TenantSdkEnvironment;
-    /** Node URL for `getScriptVersion` during business contract execution. Falls back to `baseUrl`. */
+    /** Node URL for `getContractVersion` during business contract execution. Falls back to `baseUrl`. */
     endpoint?: string;
     /**
      * Authenticated base client the TenantClient dispatches RPCs through.
@@ -4642,7 +4639,7 @@ interface TenantClientConfig {
     t3n?: TenantBaseClient;
     baseUrl?: string;
     tenantDid?: string;
-    tenantScriptName?: string;
+    tenantContractId?: string;
 }
 type TenantStatus = "pending" | "active" | "suspended";
 interface TenantMeResponse {
@@ -5092,5 +5089,5 @@ declare function tenantDidHex(tenantDid: string): string;
 declare function validateTail(tail: string): string;
 declare function canonicalTenantName(tenantDid: string, tail: string): string;
 
-export { AGENT_CARDS_SCOPE, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, InvokeError, 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, buildSecretWriteArgs, bytesToString, canonicalTenantName, clearKeyCache, clearManifestVersionFloor, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, fetchTrustedManifest, formatTokens, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, invoke, isAgentCardResponse, isDataGetResponse, isDataListResponse, isListAgentsResponse, isListHumanMembersResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isSecretListResponse, isSecretRecord, isSecretView, isUnsafeTrustServer, loadConfig, loadWasmComponent, manifestToTrustAnchor, maskKeyMaterial, mergeAgentAuthEntries, mergeDiscoverDids, metamask_get_address, metamask_sign, parseAgentAuthGet, parseAgentAuthPolicy, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toAgentAuthUpdateWire, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyManifestSignature, verifyTdxQuote };
-export type { ActivityCallerType, ActivityEntry, ActivityOutcome, ActivityReport, AdmitForOrgOptions, AgentAuthEntry, AgentAuthMergeResult, AgentAuthPolicy, AgentAuthScriptGrant, AgentAuthUpdateInput, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractDescriptorFacets, ContractExecuteInput, ContractKind, ContractLifecycleStatus, ContractListDetailedOptions, ContractListDetailedPage, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, DetailedContract, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, GetActivityLogOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, HumanMember, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListHumanMembersInput, ListHumanMembersResponse, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MemberRole, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SecretKind, SecretListInput, SecretListResponse, SecretNameInput, SecretRecord, SecretSetValueInput, SecretView, SecretWriteInput, SessionCrypto, SessionId, SetGrantsInput, SetRoleInput, SetWritersInput, SignedTrustManifest, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserGrant, UserInputProfile, UserUpsertErrorKind, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };
+export { AGENT_CARDS_SCOPE, AuthMethod, AuthenticationError, BASE_UNITS_PER_TOKEN, ContractResponseError, DEFAULT_ENVIRONMENT, DEFAULT_INDIVIDUAL_THRESHOLD_CENTS, DEFAULT_KYC_POLL_CADENCE, HandshakeError, HttpTransport, InvokeError, 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, buildSecretWriteArgs, bytesToString, canonicalTenantName, clearKeyCache, clearManifestVersionFloor, compactDidFromBytes, createDefaultHandlers, createEmailOtpAuthInput, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createOrgDataClientFromSession, createRandomHandler, createUsageReportClientFromSession, createWorkloadAuthInput, decodeWasmErrorMessage, deriveAgentCardEntryId, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, fetchTrustedManifest, formatTokens, generateRandomString, generateUUID, getContractVersion, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, invoke, isAgentCardResponse, isDataGetResponse, isDataListResponse, isListAgentsResponse, isListHumanMembersResponse, isMutationResponse, isObject, isOrgAdminStatus, isOrgContractGrants, isOrgPolicyMeta, isOrgPolicyView, isOrgUsageReport, isOrgWriters, isRoleAssignmentsResponse, isRoleGetResponse, isSecretListResponse, isSecretRecord, isSecretView, isUnsafeTrustServer, loadConfig, loadWasmComponent, manifestToTrustAnchor, maskKeyMaterial, mergeDiscoverDids, mergeGrants, metamask_get_address, metamask_sign, parseAgentAuthDoc, parseContractResponse, redactSecrets, redactSecretsFromJson, requestToWire, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, tenantDidHex, toBaseUnits, validateConfig, validateTail, verifyDkgAttestation, verifyManifestSignature, verifyTdxQuote };
+export type { ActivityCallerType, ActivityEntry, ActivityOutcome, ActivityReport, AdmitForOrgOptions, AgentAuthDoc, AgentCardRefInput, AgentCardResponse, AgentCardSetInput, AgentSummary, AssignRolesInput, AuthInput, BalanceRow, BoundGrant, ChargeReason, ClientAuth, ClientHandshake, ConfigValidationResult, ContractDescriptorFacets, ContractExecuteInput, ContractKind, ContractLifecycleStatus, ContractListDetailedOptions, ContractListDetailedPage, ContractPublishInput, ContractRegisterResult, ContractResponseSchema, ContractSetDescriptorInput, CreatePolicyInput, DataGetInput, DataGetResponse, DataListInput, DataListResponse, DelegationGrantKind, DelegationGrantRef, DeleteDataInput, DeleteGrantsInput, DeleteScopeInput, DetailedContract, Did, Direction, DkgAttestation, DkgVerifyResult, EmailOtpAuthInput, EmailOtpCredentials, Environment, EthAuthInput, ExecuteBusinessContractOptions, ExecuteOrgDataActionOptions, FetchTrustedManifestOptions, GetActivityLogOptions, GetUsageOptions, GrantCheckParams, GrantCheckResult, GranteeInput, GrantsGetInput, GrantsMergeResult, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, HumanMember, InvokeOptions, InvokeRequest, JsonRpcRequest, JsonRpcResponse, KycPollCadence, KycPollOptions, KycStatus, KycStatusKind, ListAgentsInput, ListAgentsResponse, ListContractsParams, ListContractsResult, ListContractsScope, ListHumanMembersInput, ListHumanMembersResponse, ListedContract, Logger, MapCreateInput, MapLifecycleStatus, MapResponse, MapUpdateInput, MapVisibility, MemberRole, MutationResponse, OidcAuthInput, OidcCredentials, OrgAdminStatus, OrgContractGrants, OrgDataActionWire, OrgDataClientOptions, OrgPolicyMeta, OrgPolicyView, OrgUsageReport, OrgUsageReportInput, OrgWriters, OtpChannel, OtpMergeSuggestion, OtpRequestInput, OtpRequestResult, OtpVerifyInput, OtpVerifyResult, PayrollRunRequest, PeerQuoteResult, PolicyGetInput, PurgeOrgInput, QuoteVerifyResult, ReaderSet, RemoveMemberGrantsInput, RoleAssignments, RoleAssignmentsResponse, RoleDefinition, RoleGetResponse, RoleGrant, RoleIdInput, SdkConfig, SecretKind, SecretListInput, SecretListResponse, SecretNameInput, SecretRecord, SecretSetValueInput, SecretView, SecretWriteInput, SessionCrypto, SessionId, SetGrantsInput, SetRoleInput, SetWritersInput, SignedTrustManifest, StringEncoding, SubmitUserInputArgs, SubmitUserInputResult, T3nClientConfig, TenantAdmitProjection, TenantAdmitStatus, TenantBaseClient, TenantClientConfig, TenantContractExecuteInput, TenantContractPublishInput, TenantContractSetDescriptorInput, TenantExecutionSession, TenantMapCreateInput, TenantMapUpdatePatch, TenantMeResponse, TenantSdkEnvironment, TenantSelfAdmitResult, TenantStatus, TenantTargetOptions, TokenTxKind, Transport, TrustAnchor, TrustAnchorOrUnsafe, TrustManifestPayload, UnassignRolesInput, UnsafeTrustServer, UpdateMetaInput, UsageEntry, UsagePage, UsageReportSignature, UserInputProfile, UserUpsertErrorKind, Validity, WasmComponent, WasmNextResult, WireBlock, WorkloadAuthInput, WriteDataInput, WriterSet, WritersGetInput };