@fairmint/canton-node-sdk 0.0.210 → 0.0.212

package/build/src/utils/external-signing/external-party-wallet.js

@@ -0,0 +1,859 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROVIDER_TRANSFER_OFFER_TTL_MS = void 0;
+exports.createExternalPartyWalletBridge = createExternalPartyWalletBridge;
+exports.buildExternalPartyCcTransferPrepareTokenPayload = buildExternalPartyCcTransferPrepareTokenPayload;
+exports.buildProviderTransferAcceptPrepareTokenPayload = buildProviderTransferAcceptPrepareTokenPayload;
+exports.normalizeExternalPartyWalletDescription = normalizeExternalPartyWalletDescription;
+exports.parseExternalPartyWalletConnectedSynchronizerId = parseExternalPartyWalletConnectedSynchronizerId;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("../../core/errors");
+const utils_1 = require("../../core/utils");
+const external_party_cc_transfer_1 = require("../amulet/external-party-cc-transfer");
+const external_party_transfer_offer_1 = require("../amulet/external-party-transfer-offer");
+const canton_response_utils_1 = require("../canton-response-utils");
+const canton_protocol_1 = require("./canton-protocol");
+const external_party_onboarding_1 = require("./external-party-onboarding");
+exports.DEFAULT_PROVIDER_TRANSFER_OFFER_TTL_MS = 24 * 60 * 60 * 1000;
+function createExternalPartyWalletBridge(options) {
+    validateRequiredString('providerPartyId', options.providerPartyId);
+    validateRequiredString('providerUserId', options.providerUserId);
+    validateRequiredString('prepareTokenSecret', options.prepareTokenSecret);
+    const now = options.now ?? Date.now;
+    const randomId = options.randomId ?? node_crypto_1.randomUUID;
+    const providerTransferOfferTtlMs = validateProviderTransferOfferTtlMs(options.providerTransferOfferTtlMs ?? exports.DEFAULT_PROVIDER_TRANSFER_OFFER_TTL_MS);
+    return {
+        async getConnectedSynchronizers() {
+            return readConnectedSynchronizers(options.ledgerClient, options.providerPartyId);
+        },
+        async getProviderSourceBalance() {
+            const validatorClient = requireValidatorClient(options.validatorClient, 'provider source balance');
+            return {
+                sourcePartyId: options.providerPartyId,
+                fetchedAt: new Date(now()).toISOString(),
+                raw: await validatorClient.getWalletBalance(),
+            };
+        },
+        async listExternalPartiesForPublicKey(input) {
+            if (input.partyName) {
+                const result = await (0, external_party_onboarding_1.getExternalPartyIdForHintAndPublicKey)(options.ledgerClient, input.partyName, input.publicKeyBase64);
+                return {
+                    publicKeyFingerprint: result.publicKeyFingerprint,
+                    parties: result.exists ? [result.partyId] : [],
+                    raw: result.raw,
+                };
+            }
+            return (0, external_party_onboarding_1.listExternalPartyIdsForPublicKey)(options.ledgerClient, input.publicKeyBase64);
+        },
+        async prepareExternalParty(input) {
+            const synchronizerId = await readRequiredConnectedSynchronizerId(options.ledgerClient, options.providerPartyId);
+            const prepared = await (0, external_party_onboarding_1.prepareExternalPartyOnboarding)({
+                ledgerClient: options.ledgerClient,
+                synchronizerId,
+                partyHint: input.partyName,
+                publicKeyBase64: input.publicKeyBase64,
+            });
+            return {
+                partyId: prepared.partyId,
+                publicKeyFingerprint: prepared.publicKeyFingerprint,
+                multiHashHex: prepared.multiHashHex,
+                synchronizerId: prepared.synchronizerId,
+                topologyTransactions: [...prepared.topologyTransactions],
+                publicKeyFormat: prepared.publicKeyFormat,
+                signingAlgorithmSpec: prepared.signingAlgorithmSpec,
+            };
+        },
+        async submitExternalPartySignature(input) {
+            (0, canton_protocol_1.assertCantonSha256MultihashHex)(input.multiHashHex);
+            const synchronizerId = await readRequiredConnectedSynchronizerId(options.ledgerClient, options.providerPartyId);
+            if (synchronizerId !== input.synchronizerId) {
+                throw new errors_1.ValidationError("Prepared Canton synchronizer no longer matches the provider's connected synchronizer", {
+                    expectedSynchronizerId: input.synchronizerId,
+                    synchronizerId,
+                });
+            }
+            const submitted = await (0, external_party_onboarding_1.submitExternalPartyOnboarding)({
+                ledgerClient: options.ledgerClient,
+                synchronizerId,
+                partyId: input.partyId,
+                publicKeyBase64: input.publicKeyBase64,
+                multiHashHex: input.multiHashHex,
+                topologyTransactions: input.topologyTransactions,
+                multiHashSignatureBase64: input.multiHashSignatureBase64,
+                ...(input.publicKeyFingerprint !== undefined ? { publicKeyFingerprint: input.publicKeyFingerprint } : {}),
+                allowAlreadyExists: true,
+            });
+            return {
+                partyId: submitted.partyId,
+                raw: submitted.raw,
+                alreadyExisted: submitted.alreadyExisted,
+            };
+        },
+        async prepareCcTransfer(input) {
+            const validatorClient = requireValidatorClient(options.validatorClient, 'CC transfer prepare');
+            const amount = normalizeAmountString(input.amount);
+            const description = normalizeDescription(input.description);
+            const publicKeyFingerprint = (0, canton_protocol_1.assertCantonPartyMatchesPublicKey)({
+                partyId: input.senderPartyId,
+                publicKeyBase64: input.publicKeyBase64,
+            });
+            const prepared = await (0, external_party_cc_transfer_1.prepareExternalPartyCcTransfer)(validatorClient, {
+                senderPartyId: input.senderPartyId,
+                receiverPartyId: input.receiverPartyId,
+                amount,
+                verboseHashing: false,
+                ...(description ? { description } : {}),
+            });
+            return {
+                senderPartyId: input.senderPartyId,
+                receiverPartyId: input.receiverPartyId,
+                amount,
+                description,
+                preparedTransaction: prepared.transaction,
+                preparedTransactionHashHex: prepared.transactionHashHex,
+                transferCommandContractIdPrefix: prepared.transferCommandContractIdPrefix,
+                nonce: prepared.nonce,
+                expiresAt: prepared.expiresAt,
+                prepareToken: (0, canton_protocol_1.buildCantonPrepareToken)(options.prepareTokenSecret, buildExternalPartyCcTransferPrepareTokenPayload({
+                    provider: options.provider,
+                    network: options.network,
+                    tokenContext: input.tokenContext,
+                    senderPartyId: input.senderPartyId,
+                    receiverPartyId: input.receiverPartyId,
+                    amount,
+                    description,
+                    publicKeyFingerprint,
+                    preparedTransaction: prepared.transaction,
+                    preparedTransactionHashHex: prepared.transactionHashHex,
+                    transferCommandContractIdPrefix: prepared.transferCommandContractIdPrefix,
+                    nonce: prepared.nonce,
+                    expiresAt: prepared.expiresAt,
+                })),
+                hashingDetails: readOptionalString((0, canton_response_utils_1.objectOrEmpty)(prepared.raw), 'hashing_details'),
+            };
+        },
+        async submitCcTransfer(input, hooks = {}) {
+            const validatorClient = requireValidatorClient(options.validatorClient, 'CC transfer submit');
+            const amount = normalizeAmountString(input.amount);
+            const description = normalizeDescription(input.description);
+            const publicKeyFingerprint = (0, canton_protocol_1.assertCantonPartyMatchesPublicKey)({
+                partyId: input.senderPartyId,
+                publicKeyBase64: input.publicKeyBase64,
+                ...(input.publicKeyFingerprint !== undefined ? { publicKeyFingerprint: input.publicKeyFingerprint } : {}),
+            });
+            (0, canton_protocol_1.assertCantonPrepareToken)(options.prepareTokenSecret, input.prepareToken, buildExternalPartyCcTransferPrepareTokenPayload({
+                provider: options.provider,
+                network: options.network,
+                tokenContext: input.tokenContext,
+                senderPartyId: input.senderPartyId,
+                receiverPartyId: input.receiverPartyId,
+                amount,
+                description,
+                publicKeyFingerprint,
+                preparedTransaction: input.preparedTransaction,
+                preparedTransactionHashHex: input.preparedTransactionHashHex,
+                transferCommandContractIdPrefix: input.transferCommandContractIdPrefix,
+                nonce: input.nonce,
+                expiresAt: input.expiresAt,
+            }));
+            (0, canton_protocol_1.assertCantonHashSignature)({
+                publicKeyBase64: input.publicKeyBase64,
+                hashHex: input.preparedTransactionHashHex,
+                signatureBase64: input.signatureBase64,
+            });
+            await hooks.beforeSubmit?.();
+            let submitted;
+            try {
+                submitted = await (0, external_party_cc_transfer_1.submitExternalPartyCcTransfer)(validatorClient, {
+                    senderPartyId: input.senderPartyId,
+                    transaction: input.preparedTransaction,
+                    transactionHashSignatureHex: decodeBase64(input.signatureBase64, 'signatureBase64').toString('hex'),
+                    publicKeyHex: (0, canton_protocol_1.extractRawEd25519PublicKey)(input.publicKeyBase64).toString('hex'),
+                });
+            }
+            catch (error) {
+                try {
+                    await hooks.afterSubmitFailure?.(error);
+                }
+                catch (hookError) {
+                    throw new errors_1.OperationError('afterSubmitFailure hook failed after Canton CC transfer submit failed', errors_1.OperationErrorCode.TRANSACTION_FAILED, {
+                        senderPartyId: input.senderPartyId,
+                        submitCause: errorToContext(error),
+                        hookCause: errorToContext(hookError),
+                    });
+                }
+                throw error;
+            }
+            const raw = (0, canton_response_utils_1.objectOrEmpty)(submitted.raw);
+            const updateId = readOptionalUpdateId(submitted);
+            if (!updateId) {
+                const missingUpdateIdError = new errors_1.OperationError('Canton CC transfer submit response did not include updateId', errors_1.OperationErrorCode.TRANSACTION_FAILED, {
+                    senderPartyId: input.senderPartyId,
+                    raw,
+                });
+                try {
+                    await hooks.afterSubmitWithoutUpdateId?.({
+                        senderPartyId: input.senderPartyId,
+                        raw,
+                    });
+                }
+                catch (hookError) {
+                    throw new errors_1.OperationError('afterSubmitWithoutUpdateId hook failed after Canton CC transfer submit returned without updateId', errors_1.OperationErrorCode.TRANSACTION_FAILED, {
+                        senderPartyId: input.senderPartyId,
+                        raw,
+                        submitCause: errorToContext(missingUpdateIdError),
+                        hookCause: errorToContext(hookError),
+                    });
+                }
+                throw missingUpdateIdError;
+            }
+            const result = {
+                senderPartyId: input.senderPartyId,
+                updateId,
+                raw,
+            };
+            try {
+                await hooks.afterSubmit?.(result);
+            }
+            catch (hookError) {
+                throw new errors_1.OperationError('afterSubmit hook failed after Canton CC transfer submit succeeded', errors_1.OperationErrorCode.TRANSACTION_FAILED, {
+                    senderPartyId: input.senderPartyId,
+                    updateId,
+                    raw,
+                    hookCause: errorToContext(hookError),
+                });
+            }
+            return result;
+        },
+        async prepareProviderTransfer(input) {
+            const validatorClient = requireValidatorClient(options.validatorClient, 'provider transfer prepare');
+            const amount = normalizeAmountString(input.amount);
+            const description = normalizeDescription(input.description);
+            const publicKeyFingerprint = (0, canton_protocol_1.assertCantonPartyMatchesPublicKey)({
+                partyId: input.receiverPartyId,
+                publicKeyBase64: input.publicKeyBase64,
+            });
+            const sourceBalanceBefore = await validatorClient.getWalletBalance();
+            const preparedOffer = input.offerContractId
+                ? await readResumableProviderTransferOffer({
+                    validatorClient,
+                    receiverPartyId: input.receiverPartyId,
+                    amount,
+                    description,
+                    offerContractId: validateExistingOfferContractId(input.offerContractId),
+                    offerUpdateId: input.offerUpdateId ?? null,
+                })
+                : await createProviderTransferOffer({
+                    validatorClient,
+                    receiverPartyId: input.receiverPartyId,
+                    amount,
+                    description,
+                    expiresAt: epochMillisecondsToMicroseconds(now() + providerTransferOfferTtlMs),
+                    trackingId: buildProviderTransferTrackingId({
+                        receiverPartyId: input.receiverPartyId,
+                        amount,
+                        now: now(),
+                        randomId: randomId(),
+                    }),
+                });
+            const sourceBalanceAfter = await readOptionalProviderWalletBalance(validatorClient);
+            const commandId = input.commandId ?? `accept-provider-offer-${randomId()}`;
+            let preparedAccept;
+            try {
+                preparedAccept = await prepareProviderTransferAcceptance({
+                    ledgerClient: options.ledgerClient,
+                    validatorClient,
+                    providerPartyId: options.providerPartyId,
+                    providerUserId: options.providerUserId,
+                    offerContractId: preparedOffer.offerContractId,
+                    receiverPartyId: input.receiverPartyId,
+                    commandId,
+                });
+            }
+            catch (error) {
+                throw new errors_1.OperationError('Canton provider-funded transfer acceptance prepare failed; retry with the returned offerContractId to avoid creating a duplicate offer', errors_1.OperationErrorCode.TRANSACTION_FAILED, {
+                    cause: error instanceof Error ? error.message : String(error),
+                    sourcePartyId: options.providerPartyId,
+                    receiverPartyId: input.receiverPartyId,
+                    amount,
+                    description,
+                    offerContractId: preparedOffer.offerContractId,
+                    offerUpdateId: preparedOffer.offerUpdateId,
+                    trackingId: preparedOffer.trackingId,
+                    commandId,
+                });
+            }
+            return {
+                sourcePartyId: options.providerPartyId,
+                receiverPartyId: input.receiverPartyId,
+                amount,
+                description,
+                offerContractId: preparedOffer.offerContractId,
+                offerUpdateId: preparedOffer.offerUpdateId,
+                commandId,
+                synchronizerId: preparedAccept.synchronizerId,
+                preparedTransaction: preparedAccept.preparedTransaction,
+                preparedTransactionHashHex: preparedAccept.preparedTransactionHashHex,
+                hashingSchemeVersion: preparedAccept.hashingSchemeVersion,
+                prepareToken: (0, canton_protocol_1.buildCantonPrepareToken)(options.prepareTokenSecret, buildProviderTransferAcceptPrepareTokenPayload({
+                    provider: options.provider,
+                    network: options.network,
+                    tokenContext: input.tokenContext,
+                    sourcePartyId: options.providerPartyId,
+                    receiverPartyId: input.receiverPartyId,
+                    amount,
+                    description,
+                    publicKeyFingerprint,
+                    offerContractId: preparedOffer.offerContractId,
+                    offerUpdateId: preparedOffer.offerUpdateId,
+                    commandId,
+                    synchronizerId: preparedAccept.synchronizerId,
+                    preparedTransaction: preparedAccept.preparedTransaction,
+                    preparedTransactionHashHex: preparedAccept.preparedTransactionHashHex,
+                    hashingSchemeVersion: preparedAccept.hashingSchemeVersion,
+                })),
+                sourceBalanceBefore,
+                sourceBalanceAfter,
+                raw: {
+                    offer: preparedOffer.offer,
+                    offerStatus: preparedOffer.offerStatus,
+                    offerDisclosure: preparedAccept.offerDisclosure.raw,
+                    prepared: preparedAccept.raw,
+                },
+            };
+        },
+        async submitProviderTransfer(input) {
+            const validatorClient = requireValidatorClient(options.validatorClient, 'provider transfer submit');
+            const amount = normalizeAmountString(input.amount);
+            const description = normalizeDescription(input.description);
+            const publicKeyFingerprint = (0, canton_protocol_1.assertCantonPartyMatchesPublicKey)({
+                partyId: input.receiverPartyId,
+                publicKeyBase64: input.publicKeyBase64,
+                ...(input.publicKeyFingerprint !== undefined ? { publicKeyFingerprint: input.publicKeyFingerprint } : {}),
+            });
+            const hashingSchemeVersion = input.hashingSchemeVersion ?? 'HASHING_SCHEME_VERSION_V2';
+            (0, canton_protocol_1.assertCantonPrepareToken)(options.prepareTokenSecret, input.prepareToken, buildProviderTransferAcceptPrepareTokenPayload({
+                provider: options.provider,
+                network: options.network,
+                tokenContext: input.tokenContext,
+                sourcePartyId: options.providerPartyId,
+                receiverPartyId: input.receiverPartyId,
+                amount,
+                description,
+                publicKeyFingerprint,
+                offerContractId: input.offerContractId,
+                offerUpdateId: input.offerUpdateId,
+                commandId: input.commandId,
+                synchronizerId: input.synchronizerId,
+                preparedTransaction: input.preparedTransaction,
+                preparedTransactionHashHex: input.preparedTransactionHashHex,
+                hashingSchemeVersion,
+            }));
+            (0, canton_protocol_1.assertCantonHashSignature)({
+                publicKeyBase64: input.publicKeyBase64,
+                hashHex: input.preparedTransactionHashHex,
+                signatureBase64: input.signatureBase64,
+            });
+            const submitted = await (0, external_party_transfer_offer_1.submitExternalPartyTransferOfferAcceptance)({
+                ledgerClient: options.ledgerClient,
+                userId: options.providerUserId,
+                acceptingPartyId: input.receiverPartyId,
+                publicKeyBase64: input.publicKeyBase64,
+                publicKeyFingerprint,
+                preparedTransaction: input.preparedTransaction,
+                preparedTransactionHashHex: input.preparedTransactionHashHex,
+                signatureBase64: input.signatureBase64,
+                hashingSchemeVersion,
+                submissionId: randomId(),
+            });
+            const acceptUpdateId = readRequiredUpdateId(submitted, 'provider CC transfer accept submit');
+            const sourceBalanceAfter = await readOptionalProviderWalletBalance(validatorClient);
+            return {
+                sourcePartyId: options.providerPartyId,
+                receiverPartyId: input.receiverPartyId,
+                amount,
+                description,
+                offerContractId: input.offerContractId,
+                offerUpdateId: input.offerUpdateId,
+                acceptUpdateId,
+                updateId: acceptUpdateId,
+                sourceBalanceAfter,
+                raw: (0, canton_response_utils_1.objectOrEmpty)(submitted.raw),
+            };
+        },
+        async listActiveContracts(input) {
+            const contracts = await options.ledgerClient.getActiveContracts({
+                parties: [input.partyId],
+                ...(input.templateIds && input.templateIds.length > 0 ? { templateIds: [...input.templateIds] } : {}),
+                includeCreatedEventBlob: input.includeCreatedEventBlob ?? true,
+            });
+            if (!Array.isArray(contracts)) {
+                throw new errors_1.OperationError('Canton active contracts response did not include an array', errors_1.OperationErrorCode.TRANSACTION_FAILED);
+            }
+            return {
+                contracts: contracts.slice(0, input.limit ?? 50),
+            };
+        },
+        async getExternalPartyBalance(input) {
+            const validatorClient = requireValidatorClient(options.validatorClient, 'external party balance');
+            let raw;
+            try {
+                raw = await validatorClient.getExternalPartyBalance({ partyId: input.partyId });
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+                raw = await readExternalPartyBalanceFromActiveAmulets(options.ledgerClient, input.partyId);
+            }
+            return {
+                partyId: input.partyId,
+                fetchedAt: new Date(now()).toISOString(),
+                raw,
+            };
+        },
+    };
+}
+function buildExternalPartyCcTransferPrepareTokenPayload(input) {
+    return {
+        kind: 'external-party-cc-transfer',
+        version: 1,
+        provider: input.provider ?? null,
+        network: input.network ?? null,
+        context: normalizeTokenContext(input.tokenContext),
+        senderPartyId: input.senderPartyId,
+        receiverPartyId: input.receiverPartyId,
+        amount: input.amount,
+        description: input.description,
+        publicKeyFingerprint: input.publicKeyFingerprint,
+        preparedTransactionSha256: (0, canton_protocol_1.hashPreparedTransaction)(input.preparedTransaction),
+        preparedTransactionHashHex: input.preparedTransactionHashHex,
+        transferCommandContractIdPrefix: input.transferCommandContractIdPrefix,
+        nonce: input.nonce,
+        expiresAt: input.expiresAt,
+    };
+}
+function buildProviderTransferAcceptPrepareTokenPayload(input) {
+    return {
+        kind: 'provider-transfer-accept',
+        version: 1,
+        provider: input.provider ?? null,
+        network: input.network ?? null,
+        context: normalizeTokenContext(input.tokenContext),
+        sourcePartyId: input.sourcePartyId,
+        receiverPartyId: input.receiverPartyId,
+        amount: input.amount,
+        description: input.description,
+        publicKeyFingerprint: input.publicKeyFingerprint,
+        offerContractId: input.offerContractId,
+        offerUpdateId: input.offerUpdateId,
+        commandId: input.commandId,
+        synchronizerId: input.synchronizerId,
+        preparedTransactionSha256: (0, canton_protocol_1.hashPreparedTransaction)(input.preparedTransaction),
+        preparedTransactionHashHex: input.preparedTransactionHashHex,
+        hashingSchemeVersion: input.hashingSchemeVersion,
+    };
+}
+function normalizeExternalPartyWalletDescription(description) {
+    const normalized = description?.trim();
+    if (!normalized)
+        return null;
+    return normalized;
+}
+function parseExternalPartyWalletConnectedSynchronizerId(raw) {
+    if (!(0, utils_1.isRecord)(raw) && !Array.isArray(raw))
+        return null;
+    const direct = (0, utils_1.isRecord)(raw) ? raw['connectedSynchronizers'] : undefined;
+    const itemsField = (0, utils_1.isRecord)(raw) ? raw['items'] : undefined;
+    const items = Array.isArray(raw)
+        ? raw
+        : Array.isArray(direct)
+            ? direct
+            : Array.isArray(itemsField)
+                ? itemsField
+                : [];
+    const synchronizerIds = [];
+    for (const item of items) {
+        if (typeof item === 'string' && item.trim()) {
+            synchronizerIds.push(item.trim());
+            continue;
+        }
+        if (!(0, utils_1.isRecord)(item))
+            continue;
+        for (const key of ['synchronizerId', 'synchronizer', 'domainId', 'id']) {
+            const value = item[key];
+            if (typeof value === 'string' && value.trim()) {
+                synchronizerIds.push(value.trim());
+                break;
+            }
+        }
+    }
+    const uniqueSynchronizerIds = new Set(synchronizerIds);
+    if (uniqueSynchronizerIds.size > 1) {
+        throw new errors_1.OperationError('Canton provider reported multiple connected synchronizers', errors_1.OperationErrorCode.MISSING_DOMAIN_ID, { synchronizerIds });
+    }
+    return synchronizerIds[0] ?? null;
+}
+async function prepareProviderTransferAcceptance(input) {
+    return (0, external_party_transfer_offer_1.prepareExternalPartyTransferOfferAcceptance)({
+        ledgerClient: input.ledgerClient,
+        validatorClient: input.validatorClient,
+        providerPartyId: input.providerPartyId,
+        commandId: input.commandId,
+        userId: input.providerUserId,
+        acceptingPartyId: input.receiverPartyId,
+        offerContractId: input.offerContractId,
+        ...(input.synchronizerId ? { synchronizerId: input.synchronizerId } : {}),
+    });
+}
+async function createProviderTransferOffer(input) {
+    const offer = await input.validatorClient.createTransferOffer({
+        receiver_party_id: input.receiverPartyId,
+        amount: input.amount,
+        description: input.description ?? '',
+        expires_at: input.expiresAt,
+        tracking_id: input.trackingId,
+    });
+    const offerContractId = (0, canton_response_utils_1.readRequiredString)(offer, 'offer_contract_id', 'provider CC transfer offer');
+    const offerStatus = await readOptionalTransferOfferStatus(input.validatorClient, input.trackingId);
+    return {
+        offer,
+        offerContractId,
+        offerStatus,
+        offerUpdateId: readOptionalUpdateId(offerStatus),
+        trackingId: input.trackingId,
+    };
+}
+async function readResumableProviderTransferOffer(input) {
+    const offerList = await input.validatorClient.listTransferOffers();
+    const offer = readTransferOfferByContractId(offerList, input.offerContractId);
+    if (!offer) {
+        throw new errors_1.OperationError('Canton transfer offer was not found for provider transfer resume', errors_1.OperationErrorCode.MISSING_CONTRACT, { offerContractId: input.offerContractId });
+    }
+    assertResumedProviderTransferOfferMatches({
+        offer,
+        offerContractId: input.offerContractId,
+        receiverPartyId: input.receiverPartyId,
+        amount: input.amount,
+        description: input.description,
+    });
+    return {
+        offer,
+        offerContractId: input.offerContractId,
+        offerStatus: null,
+        offerUpdateId: input.offerUpdateId,
+        trackingId: readTransferOfferString(offer, ['trackingId', 'tracking_id'], false),
+    };
+}
+function validateExistingOfferContractId(offerContractId) {
+    const normalized = offerContractId.trim();
+    if (!normalized) {
+        throw new errors_1.ValidationError('offerContractId is required when resuming provider transfer prepare');
+    }
+    return normalized;
+}
+async function readConnectedSynchronizers(ledgerClient, providerPartyId) {
+    const raw = await ledgerClient.getConnectedSynchronizers({ party: providerPartyId });
+    return {
+        synchronizerId: parseExternalPartyWalletConnectedSynchronizerId(raw),
+        raw,
+    };
+}
+async function readRequiredConnectedSynchronizerId(ledgerClient, providerPartyId) {
+    const { synchronizerId } = await readConnectedSynchronizers(ledgerClient, providerPartyId);
+    if (synchronizerId)
+        return synchronizerId;
+    throw new errors_1.OperationError('Canton provider did not report a connected synchronizer', errors_1.OperationErrorCode.MISSING_DOMAIN_ID);
+}
+async function readExternalPartyBalanceFromActiveAmulets(ledgerClient, partyId) {
+    const contracts = await ledgerClient.getActiveContracts({
+        parties: [partyId],
+        includeCreatedEventBlob: false,
+    });
+    const amulets = readAmuletBalanceContracts(contracts, partyId);
+    return {
+        source: 'ledger-active-contracts',
+        reason: 'validator-external-party-wallet-not-found',
+        effective_unlocked_qty: sumDecimalStrings(amulets.map((amulet) => amulet.amount)),
+        effective_locked_qty: '0',
+        contracts: amulets,
+    };
+}
+function readAmuletBalanceContracts(source, ownerPartyId) {
+    if (!Array.isArray(source))
+        return [];
+    const amulets = [];
+    for (const item of source) {
+        const contractEntry = (0, utils_1.isRecord)(item) ? (0, canton_response_utils_1.objectOrEmpty)(item['contractEntry']) : {};
+        const activeContract = (0, canton_response_utils_1.objectOrEmpty)(contractEntry['JsActiveContract']);
+        const createdEvent = (0, canton_response_utils_1.objectOrEmpty)(activeContract['createdEvent']);
+        const templateId = readFirstString(createdEvent, ['templateId', 'template_id']);
+        if (!templateId?.includes(':Splice.Amulet:Amulet'))
+            continue;
+        const createArgument = (0, canton_response_utils_1.objectOrEmpty)(createdEvent['createArgument']);
+        if (createArgument['owner'] !== ownerPartyId)
+            continue;
+        const amount = (0, canton_response_utils_1.objectOrEmpty)(createArgument['amount']);
+        const initialAmount = readFirstString(amount, ['initialAmount', 'initial_amount']);
+        if (!initialAmount)
+            continue;
+        amulets.push({
+            contractId: readFirstString(createdEvent, ['contractId', 'contract_id']),
+            templateId,
+            amount: initialAmount,
+        });
+    }
+    return amulets;
+}
+function buildProviderTransferTrackingId(input) {
+    return `provider-funding-${(0, node_crypto_1.createHash)('sha256')
+        .update(`${input.receiverPartyId}:${input.amount}:${input.now}:${input.randomId}`)
+        .digest('hex')
+        .slice(0, 32)}`;
+}
+function epochMillisecondsToMicroseconds(epochMilliseconds) {
+    return epochMilliseconds * 1000;
+}
+function validateProviderTransferOfferTtlMs(providerTransferOfferTtlMs) {
+    if (!Number.isSafeInteger(providerTransferOfferTtlMs) || providerTransferOfferTtlMs <= 0) {
+        throw new errors_1.ValidationError('providerTransferOfferTtlMs must be a positive safe integer', {
+            providerTransferOfferTtlMs,
+        });
+    }
+    return providerTransferOfferTtlMs;
+}
+function requireValidatorClient(validatorClient, operation) {
+    if (!validatorClient) {
+        throw new errors_1.ConfigurationError(`validatorClient is required for ${operation}`);
+    }
+    return validatorClient;
+}
+async function readOptionalTransferOfferStatus(validatorClient, trackingId) {
+    try {
+        return await validatorClient.getTransferOfferStatus({ trackingId });
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+        return null;
+    }
+}
+async function readOptionalProviderWalletBalance(validatorClient) {
+    try {
+        return await validatorClient.getWalletBalance();
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+        return null;
+    }
+}
+function readRequiredUpdateId(source, operation) {
+    const updateId = readOptionalUpdateId(source);
+    if (updateId)
+        return updateId;
+    throw new errors_1.OperationError(`Canton ${operation} response did not include updateId`, errors_1.OperationErrorCode.TRANSACTION_FAILED);
+}
+function readOptionalUpdateId(source) {
+    if (!(0, utils_1.isRecord)(source))
+        return null;
+    for (const key of ['updateId', 'update_id', 'transaction_id', 'transactionId']) {
+        const value = source[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return readOptionalUpdateId(source['raw']);
+}
+function readOptionalString(source, key) {
+    const value = source[key];
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+function readFirstString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return null;
+}
+const CANTON_DECIMAL_AMOUNT_PATTERN = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
+function normalizeAmountString(amount) {
+    const normalized = typeof amount === 'number' ? amount.toString() : amount.trim();
+    if (typeof amount === 'number') {
+        if (!Number.isFinite(amount)) {
+            throw new errors_1.ValidationError('amount must be a finite decimal amount', { amount });
+        }
+    }
+    if (!normalized) {
+        throw new errors_1.ValidationError('amount is required', { amount });
+    }
+    if (!CANTON_DECIMAL_AMOUNT_PATTERN.test(normalized) || decimalAmountIsZero(normalized)) {
+        throw new errors_1.ValidationError('amount must be a positive decimal amount', { amount });
+    }
+    return normalized;
+}
+function decimalAmountIsZero(amount) {
+    return /^0(?:\.0+)?$/.test(amount);
+}
+function readTransferOfferByContractId(source, offerContractId) {
+    const sourceOffers = (0, utils_1.isRecord)(source) ? source['offers'] : undefined;
+    const offers = Array.isArray(sourceOffers) ? sourceOffers : source;
+    if (!Array.isArray(offers))
+        return null;
+    for (const offer of offers) {
+        if (!(0, utils_1.isRecord)(offer))
+            continue;
+        const contractId = readTransferOfferString(offer, ['contractId', 'contract_id'], false);
+        if (contractId === offerContractId)
+            return offer;
+    }
+    return null;
+}
+function assertResumedProviderTransferOfferMatches(input) {
+    const receiverPartyId = readTransferOfferString(input.offer, ['receiverPartyId', 'receiver_party_id', 'receiver', 'receiverParty'], false);
+    const amount = readTransferOfferString(input.offer, ['amount'], false);
+    const description = readTransferOfferString(input.offer, ['description'], true);
+    if (receiverPartyId === null || amount === null || description === null) {
+        const missingFields = [];
+        if (receiverPartyId === null)
+            missingFields.push('receiverPartyId');
+        if (amount === null)
+            missingFields.push('amount');
+        if (description === null)
+            missingFields.push('description');
+        throw new errors_1.OperationError('Canton transfer-offer details were unavailable for provider transfer resume', errors_1.OperationErrorCode.MISSING_CONTRACT, {
+            offerContractId: input.offerContractId,
+            missingFields,
+        });
+    }
+    const expectedDescription = input.description ?? '';
+    const amountMatches = normalizeDecimalForComparison(amount) !== null &&
+        normalizeDecimalForComparison(amount) === normalizeDecimalForComparison(input.amount);
+    if (receiverPartyId !== input.receiverPartyId || !amountMatches || description !== expectedDescription) {
+        throw new errors_1.ValidationError('Resumed provider transfer offer does not match the requested transfer details', {
+            offerContractId: input.offerContractId,
+            expected: {
+                receiverPartyId: input.receiverPartyId,
+                amount: input.amount,
+                description: expectedDescription,
+            },
+            actual: {
+                receiverPartyId,
+                amount,
+                description,
+            },
+        });
+    }
+}
+function readTransferOfferString(source, keys, allowEmpty) {
+    for (const record of readTransferOfferCandidateRecords(source)) {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === 'string') {
+                const normalized = value.trim();
+                if (normalized || allowEmpty)
+                    return normalized;
+            }
+            if (typeof value === 'number' && Number.isFinite(value)) {
+                return value.toString();
+            }
+        }
+    }
+    return null;
+}
+function readTransferOfferCandidateRecords(source) {
+    const transferOffer = (0, canton_response_utils_1.objectOrEmpty)(source['transfer_offer']);
+    const transferOfferContract = (0, canton_response_utils_1.objectOrEmpty)(transferOffer['contract']);
+    const transferOfferPayload = (0, canton_response_utils_1.objectOrEmpty)(transferOffer['payload']);
+    const offer = (0, canton_response_utils_1.objectOrEmpty)(source['offer']);
+    const offerContract = (0, canton_response_utils_1.objectOrEmpty)(offer['contract']);
+    const offerPayload = (0, canton_response_utils_1.objectOrEmpty)(offer['payload']);
+    const contract = (0, canton_response_utils_1.objectOrEmpty)(source['contract']);
+    const contractPayload = (0, canton_response_utils_1.objectOrEmpty)(contract['payload']);
+    const payload = (0, canton_response_utils_1.objectOrEmpty)(source['payload']);
+    const createArgument = (0, canton_response_utils_1.objectOrEmpty)(source['createArgument'] ?? source['create_argument']);
+    return [
+        source,
+        payload,
+        createArgument,
+        contract,
+        contractPayload,
+        offer,
+        offerPayload,
+        offerContract,
+        transferOffer,
+        transferOfferPayload,
+        transferOfferContract,
+    ];
+}
+function normalizeDecimalForComparison(amount) {
+    const normalized = amount.trim();
+    if (!/^\d+(?:\.\d+)?$/.test(normalized))
+        return null;
+    const [whole = '0', fraction = ''] = normalized.split('.');
+    const normalizedWhole = whole.replace(/^0+(?=\d)/, '') || '0';
+    const normalizedFraction = fraction.replace(/0+$/, '');
+    return normalizedFraction ? `${normalizedWhole}.${normalizedFraction}` : normalizedWhole;
+}
+function normalizeDescription(description) {
+    return normalizeExternalPartyWalletDescription(description);
+}
+function normalizeTokenContext(context) {
+    if (!context)
+        return {};
+    return Object.fromEntries(Object.entries(context).filter(([, value]) => value !== undefined));
+}
+function decodeBase64(value, label) {
+    const normalized = value.trim().replace(/-/g, '+').replace(/_/g, '/');
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(normalized) || normalized.length % 4 === 1) {
+        throw new errors_1.ValidationError(`${label} must be base64-encoded`);
+    }
+    return Buffer.from(normalized, 'base64');
+}
+function errorToContext(error) {
+    const record = (0, utils_1.isRecord)(error) ? error : {};
+    const message = typeof record['message'] === 'string' && record['message'].trim()
+        ? record['message']
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return {
+        ...(typeof record['name'] === 'string' ? { name: record['name'] } : {}),
+        message,
+        ...(record['code'] !== undefined ? { code: record['code'] } : {}),
+        ...(record['status'] !== undefined ? { status: record['status'] } : {}),
+        ...(record['context'] !== undefined ? { context: record['context'] } : {}),
+    };
+}
+function isNotFound(error) {
+    if (error instanceof errors_1.ApiError) {
+        return error.status === 404;
+    }
+    return (0, utils_1.isRecord)(error) && error['status'] === 404;
+}
+function sumDecimalStrings(values) {
+    let scale = 0;
+    const parsed = values.map((value) => {
+        const [whole = '0', fraction = ''] = value.split('.');
+        scale = Math.max(scale, fraction.length);
+        return { whole, fraction };
+    });
+    let total = 0n;
+    for (const value of parsed) {
+        const whole = BigInt(value.whole === '' ? '0' : value.whole);
+        const paddedFraction = value.fraction.padEnd(scale, '0');
+        const fraction = BigInt(paddedFraction === '' ? '0' : paddedFraction);
+        total += whole * 10n ** BigInt(scale) + fraction;
+    }
+    if (scale === 0)
+        return total.toString();
+    const divisor = 10n ** BigInt(scale);
+    const whole = total / divisor;
+    const fraction = (total % divisor).toString().padStart(scale, '0');
+    return `${whole.toString()}.${fraction}`;
+}
+function validateRequiredString(name, value) {
+    if (!value.trim()) {
+        throw new errors_1.ValidationError(`${name} is required`, { [name]: value });
+    }
+}
+//# sourceMappingURL=external-party-wallet.js.map