@terminal3/t3n-sdk 0.14.0 → 1.1.0

package/dist/index.d.ts

@@ -745,6 +745,80 @@ declare class T3nClient {
      * @throws {ContractResponseError} when the response is not valid JSON
      */
     executeAndDecode<T = unknown>(payload: unknown, schema?: ContractResponseSchema<T>): Promise<T>;
+    /**
+     * Return the authenticated user's Ethereum address from their
+     * T3N-hosted per-user wallet, as a 0x-prefixed lowercase hex string.
+     * Returns `null` if the user has no wallet yet (pre-backfill edge
+     * case — `tee:user` has not yet been migrated for this DID).
+     *
+     * Backed by the `tee:user/get-self-eth-address` contract function,
+     * which delegates to the signing host's `get-user-eth-address`
+     * primitive (T3-TS-027 §7.1). The request carries no body; the
+     * authenticated user's DID is read from session context by the host.
+     *
+     * Requires the session to be Authenticated (same precondition as
+     * {@link execute}).
+     *
+     * @throws if unauthenticated, if the node rejects the action, or if
+     *   the response is not a JSON string / `null`.
+     */
+    getSelfEthAddress(): Promise<string | null>;
+    /**
+     * Enumerate every wallet the authenticated user currently controls
+     * under T3-TS-028 multi-wallet custody.
+     *
+     * `primary` is the identity-bearing wallet — same address
+     * {@link getSelfEthAddress} returns, same address the host signs
+     * with under `sign-as-user`. `secondary` is an insertion-ordered
+     * list of archival wallets absorbed through prior
+     * {@link mergeProfiles} calls (most recent last); these are signable
+     * only via an explicit sign-with-wallet flow — never ambient.
+     *
+     * Backed by `tee:user/list-user-wallets` which delegates to the
+     * signing host's `list-user-wallets` primitive. See T3-TS-028 §7.1.
+     *
+     * @throws if unauthenticated, if the node rejects the action, or if
+     *   the response shape is unexpected.
+     */
+    listUserWallets(): Promise<{
+        primary: string;
+        secondary: string[];
+    }>;
+    /**
+     * Return the ownership audit trail for a specific wallet address.
+     *
+     * The response is an array of `AuditEntry` objects (newest last)
+     * describing every DID that has owned the wallet: `Created` at DID
+     * creation, `MergedFrom { source_did }` for every merge that pulled
+     * this wallet onto a new owner, `Abandoned` if
+     * {@link removeUserWithWalletAbandonment} was called on the last
+     * owner. Public-safe data: DIDs + timestamps + reason codes only,
+     * no key material or PII. See T3-TS-028 §4.1.
+     *
+     * @param walletAddress 0x-prefixed 40-char hex Ethereum address.
+     * @throws if the node rejects the action or if the response is not
+     *   a JSON array.
+     */
+    getWalletHistory(walletAddress: string): Promise<unknown[]>;
+    /**
+     * Remove the authenticated user's account AND explicitly abandon
+     * any wallets. Writes `Abandoned` audit rows to wallet history,
+     * clears the DID's wallet index, then runs the usual user-removal
+     * cleanup (profile, authenticators, VCs, attribution).
+     *
+     * `wallet_secrets[*]` is NOT deleted — key material stays preserved
+     * in the TEE but becomes unreachable from any DID. This path
+     * exists as an opt-in alternative to {@link removeUser}, which
+     * refuses when the DID owns wallets. Callers must sweep funds
+     * off-chain BEFORE calling this if they want to retain access —
+     * the host does not reconcile balances. See T3-TS-028 §6.2.
+     *
+     * Requires the session to be Authenticated (SelfOnly delegation).
+     *
+     * @throws if unauthenticated, if the node rejects the action, or if
+     *   the response cannot be decoded.
+     */
+    removeUserWithWalletAbandonment(): Promise<unknown>;
     /**
      * The server-minted session ID once handshake has completed, or
      * `null` beforehand (pentest M-1 / MAT-983).