@metamask-previews/keyring-controller 28.2.0-preview-66aa9ab6e → 28.2.0-preview-4a8d4a2

package/dist/VaultTransaction.d.ts

@@ -0,0 +1,247 @@
+import type { EthKeyring } from '@metamask/keyring-internal-api';
+import type { CachedEncryptionKey, KeyringEntry, KeyringMetadata, SerializedKeyring } from './KeyringController.js';
+/**
+ * The scope of a vault transaction: what it owns — and therefore what it
+ * restores on failure. Everything outside the scope is untouched, even on
+ * failure: instances, references, and all.
+ */
+export type TransactionScope = WalletTransactionScope | KeyringTransactionScope;
+/**
+ * The wallet transaction scope: the transaction owns the whole wallet —
+ * all keyrings, the unsupported keyrings, and the encryption key.
+ */
+export type WalletTransactionScope = {
+    type: 'wallet';
+    /**
+     * Decides, when the transaction commits, whether the vault is written —
+     * possibly preparing the write first (e.g. re-deriving the encryption
+     * key). The session-change status is given as a lazy check, so that
+     * policies that ignore it never pay for it.
+     */
+    persist: VaultPersistPolicy;
+};
+/**
+ * The wallet-scope persist policy: answers, when the transaction commits,
+ * whether the vault is written.
+ *
+ * The standard policy persists only when the session state changed since
+ * `begin()`; other flows force the write, decline it, or gate it on their
+ * own criterion.
+ */
+export type VaultPersistPolicy = (hasChanged: () => Promise<boolean>) => boolean | Promise<boolean>;
+/**
+ * The keyring transaction scope: the transaction owns a single keyring
+ * entry, selected or created before the transaction began.
+ */
+export type KeyringTransactionScope = {
+    type: 'keyring';
+    /**
+     * The operated keyring entry.
+     */
+    entry: KeyringEntry;
+    /**
+     * Whether the transaction created the operated keyring entry.
+     */
+    created: boolean;
+};
+/**
+ * The live vault session state the transactions operate on: what the
+ * transaction snapshots at `begin()`, mutates through, and restores on
+ * `rollback()`. The controller owns the real state and implements this
+ * interface; every member reads or rewrites the state it owns.
+ */
+export type VaultSession = {
+    /**
+     * The keyrings currently registered, as a fresh array: mutations go
+     * through the other members.
+     */
+    getKeyrings(): KeyringEntry[];
+    /**
+     * Replace the registered keyrings wholesale.
+     */
+    replaceKeyrings(keyrings: KeyringEntry[]): void;
+    /**
+     * Remove the given entry from the registered keyrings, without touching
+     * the others. A no-op for an entry that is not registered: a missing
+     * entry must never fall back to another position.
+     *
+     * @returns Whether the entry was registered.
+     */
+    removeKeyring(entry: KeyringEntry): boolean;
+    /**
+     * Insert the given entry at the given position in the registered
+     * keyrings.
+     */
+    insertKeyringAt(index: number, entry: KeyringEntry): void;
+    /**
+     * The unsupported keyrings currently parked, as a fresh array.
+     */
+    getUnsupportedKeyrings(): SerializedKeyring[];
+    /**
+     * Replace the unsupported keyrings wholesale.
+     */
+    setUnsupportedKeyrings(keyrings: SerializedKeyring[]): void;
+    /**
+     * Park the given serialized keyring in the unsupported keyrings.
+     */
+    parkUnsupportedKeyring(keyring: SerializedKeyring): void;
+    /**
+     * The cached encryption key, if any.
+     */
+    getEncryptionKey(): CachedEncryptionKey | undefined;
+    /**
+     * Set, or clear, the cached encryption key.
+     */
+    setEncryptionKey(key: CachedEncryptionKey | undefined): void;
+};
+/**
+ * The controller-owned primitives the transactions drive: building new
+ * keyring entries, and enforcing the no-duplicate-accounts invariant on an
+ * explicit list of keyrings.
+ */
+export type VaultOperations = {
+    /**
+     * Build a keyring entry from its serialized parts, without registering
+     * it.
+     */
+    createKeyring(type: string, data?: unknown, metadata?: KeyringMetadata): Promise<KeyringEntry>;
+    /**
+     * Assert that the given keyrings hold no duplicate account.
+     *
+     * @throws If the keyrings hold a duplicate account.
+     */
+    assertNoDuplicateAccounts(keyrings: EthKeyring[]): Promise<void>;
+    /**
+     * Update the vault with the current session state.
+     */
+    updateVault(): Promise<boolean>;
+};
+/**
+ * The context of an in-flight vault transaction.
+ *
+ * Every mutation of the vault session runs inside a transaction, created
+ * before the mutation begins. The transaction states what it owns — its
+ * scope — and tracks what the mutation did to what it owns: `begin()`
+ * takes the snapshot that defines the restore point, `rollback()` restores
+ * exactly what the scope owns on failure, `hasChanged()` answers whether
+ * the scope changed, and `commit()` persists what it owns when its scope
+ * says so — the wallet scope's persist policy decides, the keyring scope
+ * persists iff the operated keyring changed.
+ *
+ * ## Contract
+ *
+ * 1. Every mutation runs inside a transaction. The transaction snapshots
+ *    exactly what it owns, before any mutation.
+ * 2. On failure, the transaction restores exactly what it owns.
+ *    Everything outside its scope is untouched — instances, references,
+ *    and all.
+ * 3. Mutations made outside a transaction (e.g. through instances handed
+ *    out by deprecated direct-access getters) are undefined behavior — a
+ *    bug in the caller, not an input the transaction defends against. The
+ *    transaction does not reconcile them, and must not amplify them.
+ * 4. On success, nothing is destroyed or rebuilt; instances survive in
+ *    place and references remain valid.
+ * 5. When a rebuild is necessary (failure path only), the stale instance
+ *    is always destroyed before its replacement is created, as it must
+ *    release the resources shared with the replacement (e.g. the SDK
+ *    singleton of hardware keyrings) before the replacement is
+ *    initialized.
+ *
+ * The transaction is also the home of the data it accumulates about
+ * itself, which must not outlive it: the keyring instances it destroyed,
+ * including partially destroyed ones — destruction releases resources
+ * that `serialize()` does not capture (e.g. the bridge of a hardware
+ * keyring), so a rollback must rebuild a destroyed instance even when its
+ * serialized state still matches its snapshot.
+ */
+export declare class VaultTransaction {
+    #private;
+    /**
+     * @param scope - What the transaction owns.
+     * @param session - The vault session state the transaction operates on.
+     * @param operations - The controller-owned primitives the transaction
+     *   drives.
+     */
+    constructor(scope: TransactionScope, session: VaultSession, operations: VaultOperations);
+    /**
+     * What the transaction owns — and therefore what it restores on failure.
+     *
+     * @returns The transaction scope.
+     */
+    get scope(): TransactionScope;
+    /**
+     * Take the pre-mutation snapshot that defines the restore point: every
+     * keyring of the wallet for the wallet scope, the operated keyring for
+     * the keyring scope (skipped when the transaction created it), plus the
+     * wholesale-captured session state.
+     *
+     * Must be called once, before the transaction's first mutation; a
+     * failure leaves the session untouched.
+     */
+    begin(): Promise<void>;
+    /**
+     * Check whether what the scope owns has changed since `begin()`.
+     *
+     * For the keyring scope, the operated keyring is resolved by identity:
+     * another keyring sharing its id must not affect the decision. For the
+     * wallet scope, the whole session state — the serialized keyrings, the
+     * unsupported keyrings, and the encryption key — is compared against the
+     * state captured at `begin()`.
+     *
+     * @returns Whether the scope has changed.
+     */
+    hasChanged(): Promise<boolean>;
+    /**
+     * Persist what the scope owns, iff it changed: the keyring scope
+     * persists the vault when the operated keyring changed, and the wallet
+     * scope when its persist policy says so.
+     *
+     * Must be called while the controller mutex is held, after `begin()` and
+     * a successful operation.
+     */
+    commit(): Promise<void>;
+    /**
+     * Restore what the scope owns from the snapshot taken at `begin()`:
+     * every keyring of the wallet, plus the unsupported keyrings and the
+     * encryption key, for the wallet scope; the single operated keyring for
+     * the keyring scope. Everything outside the scope is untouched.
+     *
+     * Must be called while the controller mutex is held, and only after
+     * `begin()`.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Destroy the given keyring entry's instances, marking the keyring as
+     * destroyed by this transaction — even when the destruction fails
+     * partway, as the rollback must rebuild it rather than keep it, whatever
+     * resources it already released.
+     *
+     * @param entry - The keyring entry to destroy.
+     * @param options - Destroy options.
+     * @param options.ignoreErrors - Whether to log destruction errors
+     *   instead of throwing them: a rollback must not let them mask the
+     *   transaction's own error.
+     */
+    destroy(entry: KeyringEntry, { ignoreErrors }?: {
+        ignoreErrors: boolean;
+    }): Promise<void>;
+    /**
+     * Check whether the given keyring entry's keyring was destroyed during
+     * this transaction, including partially: such a keyring must be treated
+     * as changed by the transaction, and rebuilt on rollback, even when its
+     * serialized state still matches its snapshot.
+     *
+     * @param entry - The keyring entry to check.
+     * @returns Whether the entry's keyring was destroyed.
+     */
+    isDestroyed(entry: KeyringEntry): boolean;
+    /**
+     * Remove the given keyring entry from the session keyrings, destroying
+     * its instances. A no-op for an entry that is not registered: a missing
+     * entry must never fall back to another position.
+     *
+     * @param entry - The keyring entry to remove.
+     */
+    remove(entry: KeyringEntry): Promise<void>;
+}
+//# sourceMappingURL=VaultTransaction.d.ts.map

package/dist/VaultTransaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VaultTransaction.d.ts","sourceRoot":"","sources":["../src/VaultTransaction.ts"],"names":[],"mappings":"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"}