@openzeppelin/guardian-operator-client 0.14.6 → 0.15.0-rc.0

package/dist/http.js

@@ -14,7 +14,32 @@ const DASHBOARD_ERROR_CODES = new Set([
     // Snapshot-specific codes (FR-045).
     'unsupported_for_network',
     'account_data_unavailable',
+    // Server emits SCREAMING_SNAKE_CASE; the TS union surfaces snake_case
+    // to match the rest of the DashboardErrorCode vocabulary.
+    // `parseErrorBody` does the mapping at the boundary.
+    'insufficient_operator_permission',
+    // Same wire-form / TS-form mapping as `insufficient_operator_permission`.
+    'account_paused',
 ]);
+/** Server-emitted wire form for the permission-denial error code. */
+const WIRE_INSUFFICIENT_OPERATOR_PERMISSION = 'GUARDIAN_INSUFFICIENT_OPERATOR_PERMISSION';
+/** Server-emitted wire form for the account-paused error code. */
+const WIRE_ACCOUNT_PAUSED = 'GUARDIAN_ACCOUNT_PAUSED';
+/**
+ * Map a server-emitted error `code` to the typed
+ * {@link DashboardErrorCode} surface. The only mapping today is for
+ * the permission-denial code; every other code matches by string
+ * equality.
+ */
+function mapDashboardErrorCode(raw) {
+    if (raw === WIRE_INSUFFICIENT_OPERATOR_PERMISSION) {
+        return 'insufficient_operator_permission';
+    }
+    if (raw === WIRE_ACCOUNT_PAUSED) {
+        return 'account_paused';
+    }
+    return raw;
+}
 /**
  * Parse an error response body into a typed `{ code, message }` shape.
  * Clients SHOULD branch on `code` rather than on the HTTP status alone
@@ -59,14 +84,55 @@ export async function parseErrorBody(response) {
     }
     const record = raw;
     const codeRaw = record['code'];
-    const code = typeof codeRaw === 'string' ? codeRaw : null;
+    const code = mapDashboardErrorCode(typeof codeRaw === 'string' ? codeRaw : null);
     const messageRaw = record['error'];
     const message = typeof messageRaw === 'string' ? messageRaw : null;
     const retryRaw = record['retry_after_secs'];
     const retryAfterSecs = typeof retryRaw === 'number' && Number.isInteger(retryRaw)
         ? retryRaw
         : undefined;
-    return { code, message, retryAfterSecs };
+    // Feature 006-operator-authz FR-016: populate `missingPermissions`
+    // and `retryable` only when the server emitted the permission-denial
+    // code. Every other code path leaves both fields undefined so the
+    // additive envelope extension is invisible to existing parsers. The
+    // contract pins `retryable=false` for this code; surface that
+    // unconditionally so a non-compliant server can't mislead retry
+    // policy code into retrying a permission denial.
+    let missingPermissions;
+    let retryable;
+    let pausedAt;
+    let pausedReason;
+    if (code === 'insufficient_operator_permission') {
+        const missingRaw = record['missing_permissions'];
+        if (Array.isArray(missingRaw) &&
+            missingRaw.every((v) => typeof v === 'string')) {
+            missingPermissions = missingRaw;
+        }
+        retryable = false;
+    }
+    else if (code === 'account_paused') {
+        const pausedAtRaw = record['paused_at'];
+        if (typeof pausedAtRaw === 'string') {
+            pausedAt = pausedAtRaw;
+        }
+        const reasonRaw = record['paused_reason'];
+        if (typeof reasonRaw === 'string') {
+            pausedReason = reasonRaw;
+        }
+        else if (reasonRaw === null) {
+            pausedReason = null;
+        }
+        retryable = false;
+    }
+    return {
+        code,
+        message,
+        retryAfterSecs,
+        missingPermissions,
+        retryable,
+        pausedAt,
+        pausedReason,
+    };
 }
 /**
  * Type guard narrowing an arbitrary string to {@link DashboardErrorCode}.
@@ -143,8 +209,19 @@ export class GuardianOperatorHttpClient {
     async listAccounts(options = {}) {
         const url = new URL('dashboard/accounts', this.baseUrl);
         applyPaginationParams(url, options);
+        if (options.paused !== undefined) {
+            url.searchParams.set('paused', String(options.paused));
+        }
         return this.request(url, { method: 'GET' }, parseAccountListPage);
     }
+    /**
+     * Return the authenticated operator's identity and effective
+     * permission set. Succeeds for any valid session, including
+     * operators with `permissions: []` (returns an empty array).
+     */
+    async getSession() {
+        return this.request(new URL('dashboard/session', this.baseUrl), { method: 'GET' }, parseSessionInfo);
+    }
     /**
      * Inventory and lifecycle health snapshot per feature
      * `005-operator-dashboard-metrics` US2 / FR-008..FR-012.
@@ -152,6 +229,28 @@ export class GuardianOperatorHttpClient {
     async getDashboardInfo() {
         return this.request(new URL('dashboard/info', this.baseUrl), { method: 'GET' }, parseDashboardInfo);
     }
+    /**
+     * Pause mutating actions for the given account. Requires
+     * `accounts:pause`. Idempotent: re-pausing an already-paused account
+     * returns success with the original `pausedAt` preserved.
+     */
+    async pauseAccount(accountId, reason) {
+        const encoded = encodeURIComponent(accountId);
+        return this.request(new URL(`dashboard/accounts/${encoded}/pause`, this.baseUrl), { method: 'POST', body: JSON.stringify({ reason }) }, parsePauseResponse);
+    }
+    /**
+     * Clear pause state for the given account. Requires `accounts:pause`.
+     * Idempotent: unpausing an already-active account returns success
+     * with no state change.
+     */
+    async unpauseAccount(accountId, reason) {
+        const encoded = encodeURIComponent(accountId);
+        const init = { method: 'POST' };
+        if (reason !== undefined) {
+            init.body = JSON.stringify({ reason });
+        }
+        return this.request(new URL(`dashboard/accounts/${encoded}/unpause`, this.baseUrl), init, parseUnpauseResponse);
+    }
     async getAccount(accountId) {
         const encodedAccountId = encodeURIComponent(accountId);
         return this.request(new URL(`dashboard/accounts/${encodedAccountId}`, this.baseUrl), { method: 'GET' }, parseAccountResponse);
@@ -189,6 +288,23 @@ export class GuardianOperatorHttpClient {
         applyPaginationParams(url, options);
         return this.request(url, { method: 'GET' }, parseDeltaPage);
     }
+    /**
+     * Fetch the full detail projection of one canonical delta. The
+     * nonce is serialized as a canonical base-10 `u64` URL segment;
+     * unknown account and unknown nonce both surface as
+     * `404 delta_not_found`.
+     */
+    async getAccountDeltaDetail(accountId, nonce, options = {}) {
+        if (!Number.isSafeInteger(nonce) || nonce < 0) {
+            throw new GuardianOperatorContractError('getAccountDeltaDetail.nonce', `nonce must be a non-negative safe integer, got ${nonce}`);
+        }
+        const encodedAccountId = encodeURIComponent(accountId);
+        const url = new URL(`dashboard/accounts/${encodedAccountId}/deltas/${nonce.toString()}`, this.baseUrl);
+        if (options.includeRaw) {
+            url.searchParams.set('include', 'raw');
+        }
+        return this.request(url, { method: 'GET' }, parseDeltaDetail);
+    }
     /**
      * List the per-account in-flight multisig proposal queue for
      * `accountId`, paginated newest-first by `(nonce DESC, commitment
@@ -353,6 +469,30 @@ function parseLogoutResponse(value) {
         success: requireSuccess(record, 'logout response'),
     };
 }
+function parseSessionInfo(value) {
+    const record = asRecord(value, 'session response');
+    const permissions = requireStringArray(record, 'permissions', 'session response');
+    for (const [index, permission] of permissions.entries()) {
+        if (!KNOWN_OPERATOR_PERMISSIONS.has(permission)) {
+            throw new GuardianOperatorContractError('session response', `permissions[${index}] is not a known operator permission: ${JSON.stringify(permission)}`);
+        }
+    }
+    return {
+        operatorId: requireString(record, 'operator_id', 'session response'),
+        permissions: permissions,
+    };
+}
+/**
+ * Stable v1 operator permission vocabulary. Mirrors
+ * `crates/server/src/dashboard/permissions.rs::Permission::as_str`.
+ * Surfaces server/client drift as a contract failure instead of
+ * silently flowing unknown strings through.
+ */
+const KNOWN_OPERATOR_PERMISSIONS = new Set([
+    'dashboard:read',
+    'accounts:pause',
+    'policies:write',
+]);
 function parseAccountListPage(value) {
     return parsePagedResult(value, parseAccountSummary, 'accounts page');
 }
@@ -460,7 +600,7 @@ function parseAccountSnapshot(value) {
 }
 function parseAccountSummary(value, context) {
     const record = asRecord(value, context);
-    return {
+    const summary = {
         accountId: requireString(record, 'account_id', context),
         authScheme: requireString(record, 'auth_scheme', context),
         authorizedSignerCount: requireInteger(record, 'authorized_signer_count', context),
@@ -469,7 +609,16 @@ function parseAccountSummary(value, context) {
         stateStatus: parseStateStatus(requireString(record, 'state_status', context), `${context}.state_status`),
         createdAt: requireString(record, 'created_at', context),
         updatedAt: requireString(record, 'updated_at', context),
+        pausedAt: requireNullableString(record, 'paused_at', context),
+        pausedReason: requireNullableString(record, 'paused_reason', context),
     };
+    if (record.account_id_bech32 !== undefined && record.account_id_bech32 !== null) {
+        if (typeof record.account_id_bech32 !== 'string') {
+            throw new GuardianOperatorContractError(context, 'account_id_bech32 must be a string when present');
+        }
+        summary.accountIdBech32 = record.account_id_bech32;
+    }
+    return summary;
 }
 function parseAccountDetail(value, context) {
     const summary = parseAccountSummary(value, context);
@@ -481,6 +630,33 @@ function parseAccountDetail(value, context) {
         stateUpdatedAt: requireNullableString(record, 'state_updated_at', context),
     };
 }
+function parseAccountStatus(value, context) {
+    if (value === 'active' || value === 'paused') {
+        return value;
+    }
+    throw new GuardianOperatorContractError(context, `expected account status "active" or "paused", got ${JSON.stringify(value)}`);
+}
+function parsePauseResponse(value) {
+    const ctx = 'pause response';
+    const record = asRecord(value, ctx);
+    return {
+        accountId: requireString(record, 'account_id', ctx),
+        beforeState: parseAccountStatus(requireString(record, 'before_state', ctx), `${ctx}.before_state`),
+        afterState: parseAccountStatus(requireString(record, 'after_state', ctx), `${ctx}.after_state`),
+        pausedAt: requireString(record, 'paused_at', ctx),
+        pausedReason: requireString(record, 'paused_reason', ctx),
+    };
+}
+function parseUnpauseResponse(value) {
+    const ctx = 'unpause response';
+    const record = asRecord(value, ctx);
+    return {
+        accountId: requireString(record, 'account_id', ctx),
+        beforeState: parseAccountStatus(requireString(record, 'before_state', ctx), `${ctx}.before_state`),
+        afterState: parseAccountStatus(requireString(record, 'after_state', ctx), `${ctx}.after_state`),
+        reason: requireNullableString(record, 'reason', ctx),
+    };
+}
 function parseErrorResponse(value) {
     const record = asRecord(value, 'error response');
     const success = requireBoolean(record, 'success', 'error response');
@@ -505,13 +681,64 @@ function parseErrorResponse(value) {
         if (typeof codeValue !== 'string') {
             throw new GuardianOperatorContractError('error response', 'code must be a string when present');
         }
-        code = codeValue;
+        code = mapDashboardErrorCode(codeValue) ?? undefined;
+    }
+    // Feature 006-operator-authz FR-016: populate `missingPermissions`
+    // and `retryable` only on the permission-denial code. Tolerate
+    // either ordering or omission on every other code so legacy 5xx /
+    // 4xx errors continue to parse byte-for-byte as before.
+    let missingPermissions;
+    let retryable;
+    let pausedAt;
+    let pausedReason;
+    if (code === 'insufficient_operator_permission') {
+        const missingRaw = record.missing_permissions;
+        if (missingRaw !== undefined) {
+            if (!Array.isArray(missingRaw) ||
+                !missingRaw.every((v) => typeof v === 'string')) {
+                throw new GuardianOperatorContractError('error response', 'missing_permissions must be an array of strings');
+            }
+            missingPermissions = missingRaw;
+        }
+        const retryableRaw = record.retryable;
+        if (retryableRaw !== undefined) {
+            if (retryableRaw !== false) {
+                // FR-016 pins `retryable: false` for permission denials.
+                // Surface server contract drift loudly rather than letting
+                // retry policy code retry an unretryable failure.
+                throw new GuardianOperatorContractError('error response', 'retryable must be false for insufficient_operator_permission');
+            }
+            retryable = false;
+        }
+    }
+    else if (code === 'account_paused') {
+        const pausedAtRaw = record.paused_at;
+        if (typeof pausedAtRaw !== 'string') {
+            throw new GuardianOperatorContractError('error response', 'paused_at must be a string for account_paused');
+        }
+        pausedAt = pausedAtRaw;
+        const reasonRaw = record.paused_reason;
+        if (typeof reasonRaw === 'string' || reasonRaw === null) {
+            pausedReason = reasonRaw;
+        }
+        else if (reasonRaw !== undefined) {
+            throw new GuardianOperatorContractError('error response', 'paused_reason must be a string or null for account_paused');
+        }
+        const retryableRaw = record.retryable;
+        if (retryableRaw !== undefined && retryableRaw !== false) {
+            throw new GuardianOperatorContractError('error response', 'retryable must be false for account_paused');
+        }
+        retryable = false;
     }
     return {
         success: false,
         code,
         error: requireString(record, 'error', 'error response'),
         retryAfterSecs,
+        missingPermissions,
+        retryable,
+        pausedAt,
+        pausedReason,
     };
 }
 function parseStateStatus(value, context) {
@@ -585,6 +812,20 @@ function requireStringArray(record, key, context) {
         return entry;
     });
 }
+function requireNonNegativeInteger(value, key, context) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new GuardianOperatorContractError(context, `field "${key}" must be a non-negative integer`);
+    }
+    return value;
+}
+function assertStringArray(value, key, context) {
+    value.forEach((entry, index) => {
+        if (typeof entry !== 'string') {
+            throw new GuardianOperatorContractError(context, `field "${key}" entry ${index} must be a string`);
+        }
+    });
+    return value;
+}
 // ---------------------------------------------------------------------------
 // Pagination helpers — feature `005-operator-dashboard-metrics`.
 // ---------------------------------------------------------------------------
@@ -660,12 +901,24 @@ function parseDeltaEntry(value, context) {
         }
         entry.accountId = record.account_id;
     }
+    if (record.category !== undefined && record.category !== null) {
+        entry.category = parseDeltaCategory(requireString(record, 'category', context), `${context}.category`);
+    }
     if (record.proposal_type !== undefined) {
         if (typeof record.proposal_type !== 'string') {
             throw new GuardianOperatorContractError(context, 'proposal_type must be a string when present');
         }
         entry.proposalType = record.proposal_type;
     }
+    if (record.note_counts !== undefined && record.note_counts !== null) {
+        entry.noteCounts = parseDeltaNoteCounts(requireField(record, 'note_counts', context), `${context}.note_counts`);
+    }
+    if (record.assets !== undefined) {
+        entry.assets = parseDeltaAssetSummaryArray(record.assets, `${context}.assets`);
+    }
+    if (record.counterparty !== undefined && record.counterparty !== null) {
+        entry.counterparty = parseDeltaCounterpartySummary(record.counterparty, `${context}.counterparty`);
+    }
     return entry;
 }
 function parseProposalEntry(value, context) {
@@ -694,6 +947,254 @@ function parseProposalEntry(value, context) {
     }
     return entry;
 }
+const DELTA_CATEGORY_VALUES = [
+    'asset_transfer',
+    'note_consumption',
+    'note_creation',
+    'account_storage_change',
+    'guardian_switch',
+    'custom',
+];
+function parseDeltaCategory(value, context) {
+    if (DELTA_CATEGORY_VALUES.includes(value)) {
+        return value;
+    }
+    throw new GuardianOperatorContractError(context, `invalid category "${value}" — expected one of ${DELTA_CATEGORY_VALUES.join(', ')}`);
+}
+function parseDeltaAssetSummary(value, context) {
+    const record = asRecord(value, context);
+    const kind = requireString(record, 'kind', context);
+    if (kind !== 'fungible' && kind !== 'non_fungible') {
+        throw new GuardianOperatorContractError(context, `asset kind must be "fungible" or "non_fungible", got "${kind}"`);
+    }
+    const asset = {
+        assetId: requireString(record, 'asset_id', context),
+        kind: kind,
+    };
+    if (record.amount !== undefined && record.amount !== null) {
+        if (typeof record.amount !== 'string') {
+            throw new GuardianOperatorContractError(context, 'asset amount must be a string when present');
+        }
+        asset.amount = record.amount;
+    }
+    return asset;
+}
+function parseDeltaAssetSummaryArray(value, context) {
+    if (!Array.isArray(value)) {
+        throw new GuardianOperatorContractError(context, 'expected an array');
+    }
+    return value.map((item, index) => parseDeltaAssetSummary(item, `${context}[${index}]`));
+}
+function parseDeltaCounterpartySummary(value, context) {
+    const record = asRecord(value, context);
+    const direction = requireString(record, 'direction', context);
+    if (direction !== 'in' && direction !== 'out') {
+        throw new GuardianOperatorContractError(context, `counterparty direction must be "in" or "out", got "${direction}"`);
+    }
+    return {
+        accountId: requireString(record, 'account_id', context),
+        direction: direction,
+    };
+}
+function parseDeltaNoteCounts(value, context) {
+    const record = asRecord(value, context);
+    const input = requireInteger(record, 'input', context);
+    const output = requireInteger(record, 'output', context);
+    if (input < 0 || output < 0) {
+        throw new GuardianOperatorContractError(context, 'note counts must be non-negative integers');
+    }
+    return { input, output };
+}
+function parseDeltaProposalMetadata(value, context) {
+    const record = asRecord(value, context);
+    const proposal = {
+        proposalType: requireString(record, 'proposal_type', context),
+    };
+    if (typeof record.description === 'string')
+        proposal.description = record.description;
+    if (typeof record.salt === 'string')
+        proposal.salt = record.salt;
+    if (record.required_signatures !== undefined)
+        proposal.requiredSignatures = requireNonNegativeInteger(record.required_signatures, 'required_signatures', context);
+    if (typeof record.recipient_id === 'string')
+        proposal.recipientId = record.recipient_id;
+    if (typeof record.faucet_id === 'string')
+        proposal.faucetId = record.faucet_id;
+    if (typeof record.amount === 'string')
+        proposal.amount = record.amount;
+    if (record.note_ids !== undefined)
+        proposal.noteIds = assertStringArray(requireArray(record, 'note_ids', context), 'note_ids', context);
+    if (record.consume_notes_metadata_version !== undefined)
+        proposal.consumeNotesMetadataVersion = requireNonNegativeInteger(record.consume_notes_metadata_version, 'consume_notes_metadata_version', context);
+    if (record.consume_notes_notes !== undefined)
+        proposal.consumeNotesNotes = assertStringArray(requireArray(record, 'consume_notes_notes', context), 'consume_notes_notes', context);
+    if (record.target_threshold !== undefined)
+        proposal.targetThreshold = requireNonNegativeInteger(record.target_threshold, 'target_threshold', context);
+    if (record.signer_commitments !== undefined)
+        proposal.signerCommitments = assertStringArray(requireArray(record, 'signer_commitments', context), 'signer_commitments', context);
+    if (typeof record.new_guardian_pubkey === 'string')
+        proposal.newGuardianPubkey = record.new_guardian_pubkey;
+    if (typeof record.new_guardian_endpoint === 'string')
+        proposal.newGuardianEndpoint = record.new_guardian_endpoint;
+    if (typeof record.target_procedure === 'string')
+        proposal.targetProcedure = record.target_procedure;
+    return proposal;
+}
+function parseDeltaDetail(value) {
+    const ctx = 'delta detail';
+    const record = asRecord(value, ctx);
+    const detail = {
+        accountId: requireString(record, 'account_id', ctx),
+        nonce: requireInteger(record, 'nonce', ctx),
+        status: parseDeltaStatus(requireString(record, 'status', ctx), `${ctx}.status`),
+        statusTimestamp: requireString(record, 'status_timestamp', ctx),
+        prevCommitment: requireString(record, 'prev_commitment', ctx),
+        newCommitment: requireNullableString(record, 'new_commitment', ctx),
+        inputNotes: parseDecodedNoteArray(requireField(record, 'input_notes', ctx), `${ctx}.input_notes`),
+        outputNotes: parseDecodedNoteArray(requireField(record, 'output_notes', ctx), `${ctx}.output_notes`),
+        vaultChanges: parseVaultChangeArray(requireField(record, 'vault_changes', ctx), `${ctx}.vault_changes`),
+        storageChanges: parseStorageChangeArray(requireField(record, 'storage_changes', ctx), `${ctx}.storage_changes`),
+    };
+    if (record.retry_count !== undefined) {
+        const retry = record.retry_count;
+        if (typeof retry !== 'number' || !Number.isInteger(retry) || retry < 0) {
+            throw new GuardianOperatorContractError(ctx, 'retry_count must be a non-negative integer when present');
+        }
+        detail.retryCount = retry;
+    }
+    if (record.category !== undefined && record.category !== null) {
+        detail.category = parseDeltaCategory(requireString(record, 'category', ctx), `${ctx}.category`);
+    }
+    if (record.proposal !== undefined && record.proposal !== null) {
+        detail.proposal = parseDeltaProposalMetadata(record.proposal, `${ctx}.proposal`);
+    }
+    if (Array.isArray(record.decode_warnings) && record.decode_warnings.length > 0) {
+        detail.decodeWarnings = record.decode_warnings.map((w, i) => parseDecodeWarning(w, `${ctx}.decode_warnings[${i}]`));
+    }
+    if (typeof record.raw_transaction_summary === 'string') {
+        detail.rawTransactionSummary = record.raw_transaction_summary;
+    }
+    return detail;
+}
+function parseDecodedNoteArray(value, context) {
+    if (!Array.isArray(value)) {
+        throw new GuardianOperatorContractError(context, 'expected an array of decoded notes');
+    }
+    return value.map((entry, i) => parseDecodedNote(entry, `${context}[${i}]`));
+}
+const NOTE_TAG_VALUES = [
+    'p2id',
+    'p2ide',
+    'pswap',
+    'mint',
+    'burn',
+    'custom',
+];
+function parseDecodedNote(value, context) {
+    const record = asRecord(value, context);
+    const tag = requireString(record, 'tag', context);
+    if (!NOTE_TAG_VALUES.includes(tag)) {
+        throw new GuardianOperatorContractError(context, `unknown note tag "${tag}"`);
+    }
+    const assets = requireField(record, 'assets', context);
+    if (!Array.isArray(assets)) {
+        throw new GuardianOperatorContractError(context, 'assets must be an array');
+    }
+    const note = {
+        noteId: requireString(record, 'note_id', context),
+        tag: tag,
+        assets: assets.map((a, i) => parseDecodedAsset(a, `${context}.assets[${i}]`)),
+    };
+    if (typeof record.sender === 'string')
+        note.sender = record.sender;
+    if (typeof record.recipient === 'string')
+        note.recipient = record.recipient;
+    return note;
+}
+function parseDecodedAsset(value, context) {
+    const record = asRecord(value, context);
+    const kind = requireString(record, 'kind', context);
+    if (kind !== 'fungible' && kind !== 'non_fungible') {
+        throw new GuardianOperatorContractError(context, `asset kind must be "fungible" or "non_fungible", got "${kind}"`);
+    }
+    const asset = {
+        assetId: requireString(record, 'asset_id', context),
+        kind: kind,
+    };
+    if (typeof record.amount === 'string')
+        asset.amount = record.amount;
+    return asset;
+}
+function parseVaultChangeArray(value, context) {
+    if (!Array.isArray(value)) {
+        throw new GuardianOperatorContractError(context, 'expected an array of vault changes');
+    }
+    return value.map((entry, i) => parseVaultChange(entry, `${context}[${i}]`));
+}
+function parseVaultChange(value, context) {
+    const record = asRecord(value, context);
+    const kind = requireString(record, 'kind', context);
+    if (kind === 'fungible') {
+        return {
+            kind: 'fungible',
+            assetId: requireString(record, 'asset_id', context),
+            change: requireString(record, 'change', context),
+        };
+    }
+    if (kind === 'non_fungible') {
+        const added = requireField(record, 'added', context);
+        const removed = requireField(record, 'removed', context);
+        if (!Array.isArray(added) || !Array.isArray(removed)) {
+            throw new GuardianOperatorContractError(context, 'non_fungible added/removed must be arrays');
+        }
+        return {
+            kind: 'non_fungible',
+            assetId: requireString(record, 'asset_id', context),
+            added: assertStringArray(added, 'added', context),
+            removed: assertStringArray(removed, 'removed', context),
+        };
+    }
+    throw new GuardianOperatorContractError(context, `vault change kind must be "fungible" or "non_fungible", got "${kind}"`);
+}
+function parseStorageChangeArray(value, context) {
+    if (!Array.isArray(value)) {
+        throw new GuardianOperatorContractError(context, 'expected an array of storage changes');
+    }
+    return value.map((entry, i) => parseStorageChange(entry, `${context}[${i}]`));
+}
+function parseStorageChange(value, context) {
+    const record = asRecord(value, context);
+    const change = {
+        slotName: requireString(record, 'slot_name', context),
+        after: requireNullableString(record, 'after', context),
+    };
+    if (record.key !== undefined && record.key !== null) {
+        change.key = requireString(record, 'key', context);
+    }
+    if (record.before !== undefined) {
+        change.before = requireNullableString(record, 'before', context);
+    }
+    return change;
+}
+const DECODE_SECTION_VALUES = [
+    'tx_summary',
+    'metadata',
+    'input_notes',
+    'output_notes',
+    'vault',
+    'storage',
+];
+function parseDecodeWarning(value, context) {
+    const record = asRecord(value, context);
+    const section = requireString(record, 'section', context);
+    if (!DECODE_SECTION_VALUES.includes(section)) {
+        throw new GuardianOperatorContractError(context, `unknown decode section "${section}"`);
+    }
+    return {
+        section: section,
+        reason: requireString(record, 'reason', context),
+    };
+}
 function parseDeltaStatus(value, context) {
     if (value === 'candidate' || value === 'canonical' || value === 'discarded') {
         return value;