@openora/core 0.4.1-canary.91 → 0.4.1-canary.93

package/dist/wallet/service/wallet.service.js

@@ -1,24 +1,35 @@
-import { makeNotFoundError, makeConflictError, createDomainError, findOneOrThrow, pageToOffset, withAdvisoryXactLock, assertRateLimit, createLogger, moneyToNumber, moneyEquals, } from '@openora/core/server';
-import { normalizeKycStatus, } from '@openora/core/contracts';
+import { makeNotFoundError, serializeRow, makeConflictError, createDomainError, findOneOrThrow, pageToOffset, withAdvisoryXactLock, assertRateLimit, createLogger, moneyToNumber, moneyEquals, moneyAdd, moneyCompare, moneySubtract, } from '@openora/core/server';
+import { normalizeKycStatus, DEFAULT_PAYMENT_PROVIDER, } from '@openora/core/contracts';
 import { eq, asc, desc, sql, and, gte, lte, count, inArray, isNull, or } from 'drizzle-orm';
 import { createHash } from 'node:crypto';
-import { wallet, walletBalance, walletTransaction, autoWithdrawalRule, walletAutoWithdrawalConfig, walletDepositAddress, } from '../schema/index.js';
+import { wallet, walletBalance, walletTransaction, autoWithdrawalRule, walletAutoWithdrawalConfig, walletDepositAddress, walletAsset, } from '../schema/index.js';
 const logger = createLogger('wallet');
 export const WalletNotFoundError = makeNotFoundError('Wallet');
 export const WithdrawalNotFoundError = makeNotFoundError('Withdrawal');
 export const AutoWithdrawalConfigNotFoundError = makeNotFoundError('AutoWithdrawalConfig');
+export const PlayerNotFoundError = makeNotFoundError('Player');
 export const InsufficientBalanceError = createDomainError('InsufficientBalanceError', (available, requested) => `Insufficient balance: available ${available}, requested ${requested}`);
 export const WithdrawalNotPendingError = makeConflictError('WithdrawalNotPendingError', 'Withdrawal is not pending and cannot be reviewed');
 export const KycRequiredError = makeConflictError('KycRequiredError', 'KYC verification required before withdrawal');
 export const IdempotencyKeyReuseError = makeConflictError('IdempotencyKeyReuseError', 'Idempotency key was already used with a different amount');
 export const DepositAddressUnsupportedError = makeConflictError('DepositAddressUnsupportedError', 'The bound payment adapter does not support address-based deposits');
 export const DestinationAddressRequiredError = makeConflictError('DestinationAddressRequiredError', 'A destination address is required for a crypto-rail withdrawal');
+export const WalletAssetNotFoundError = makeNotFoundError('WalletAsset');
+export const WalletAssetAlreadyExistsError = makeConflictError('WalletAssetAlreadyExistsError', 'An asset is already configured for this currency and network');
+export const WalletAssetUnsupportedError = makeConflictError('WalletAssetUnsupportedError', 'The bound payment adapter cannot serve this currency and network');
+export const WalletAssetInUseError = makeConflictError('WalletAssetInUseError', 'Players still hold a balance in this currency');
+export const WalletAssetUnknownProviderError = makeConflictError('WalletAssetUnknownProviderError', 'providerName is not a registered payment provider');
+export const WalletAssetHasInFlightTransactionsError = makeConflictError('WalletAssetHasInFlightTransactionsError', 'A pending or processing transaction exists for this currency and network');
+export const AmbiguousNetworkError = createDomainError('AmbiguousNetworkError', (currency, networks) => `Currency ${currency} settles on several networks (${networks}) - a network is required`);
+export const UnsupportedNetworkError = createDomainError('UnsupportedNetworkError', (currency, network) => `Currency ${currency} is not settled on network ${network}`);
+export const WithdrawalDisabledError = createDomainError('WithdrawalDisabledError', (currency) => `Withdrawals are disabled for ${currency} on every configured network`);
+export const BelowMinimumWithdrawalError = createDomainError('BelowMinimumWithdrawalError', (amount, minimum, currency, network) => `Withdrawal of ${amount} ${currency} on ${network} is below the ${minimum} ${currency} minimum`);
 const KYC_PASS_STATUSES = new Set(['approved', 'manually_overridden']);
 export const CurrencyMismatchError = createDomainError('CurrencyMismatchError', (requested, walletCurrency) => `Currency mismatch: requested ${requested}, wallet holds ${walletCurrency}`);
 export const AmbiguousDepositAddressError = createDomainError('AmbiguousDepositAddressError', (address, network) => `Deposit address ${address} on ${network ?? 'an unknown network'} is issued to more than one user`);
-// Crypto currencies settle on the crypto rail (Fireblocks); everything else on the
-// fiat rail (a PSP). The concrete provider is recorded per transaction, not here.
-// Overridable per-operator via `platformConfig.wallet.cryptoCurrencies` - see `railFor`.
+// Crypto currencies settle on the crypto rail through a custody/MPC vendor; everything
+// else on the fiat rail (a PSP). The concrete provider is recorded per transaction, not
+// here. Overridable per-operator via `platformConfig.wallet.cryptoCurrencies` - see `railFor`.
 const DEFAULT_CRYPTO_CURRENCIES = new Set(['BTC', 'ETH', 'USDT', 'USDC']);
 // Mirrors the `wallet.currency` column default: what a player without a wallet row
 // reads as their active currency before one is created on first deposit.
@@ -27,6 +38,49 @@ const DEFAULT_WALLET_CURRENCY = 'USD';
 // fraud (idempotency + the ledger guard cover correctness). An overlay rebinds
 // RATE_LIMITER to change the backend, not this policy.
 const WALLET_MUTATION_RATE_LIMIT = { limit: 30, windowMs: 60 * 1000 };
+/**
+ * Pins the chain a payout settles on. With one payable network the choice is implied; with
+ * several an explicit network is mandatory, because picking one silently would send a
+ * player's USDT over a chain their receiving wallet may not support.
+ *
+ * `assets` is every catalog row for the currency, enabled or not, so the two empty cases
+ * stay distinguishable: no rows at all means the operator never configured this currency
+ * (a fiat PSP), and the caller's choice passes through unchecked; rows that are all
+ * withdrawal-disabled is a deliberate operator decision and fails closed.
+ */
+export function resolveWithdrawalNetwork(assets, currency, network) {
+    if (assets.length === 0) {
+        return network?.toUpperCase() ?? null;
+    }
+    const payable = assets.filter((asset) => asset.withdrawalEnabled);
+    const [only, ...rest] = payable;
+    if (!only) {
+        throw new WithdrawalDisabledError(currency);
+    }
+    if (network === undefined) {
+        if (rest.length > 0) {
+            throw new AmbiguousNetworkError(currency, payable.map((asset) => asset.network).join(', '));
+        }
+        return only.network.toUpperCase();
+    }
+    const wanted = network.toUpperCase();
+    if (!payable.some((asset) => asset.network.toUpperCase() === wanted)) {
+        throw new UnsupportedNetworkError(currency, wanted);
+    }
+    return wanted;
+}
+/**
+ * Rejects a payout worth less than the operator's per-network floor. The floor is per chain,
+ * not per currency: moving USDT costs cents on BEP20 and dollars on ERC20, so one
+ * currency-wide minimum is either too high for the cheap chain or below the fee on the
+ * expensive one.
+ */
+export function assertAboveMinimumWithdrawal(assets, amount, currency, network) {
+    const asset = assets.find((candidate) => candidate.withdrawalEnabled && candidate.network.toUpperCase() === network);
+    if (asset && moneyCompare(amount, asset.minWithdrawal) < 0) {
+        throw new BelowMinimumWithdrawalError(amount, asset.minWithdrawal, currency, asset.network);
+    }
+}
 export function railFor(currency, cryptoCurrencies) {
     const set = cryptoCurrencies
         ? new Set(cryptoCurrencies.map((c) => c.toUpperCase()))
@@ -69,6 +123,7 @@ export async function readWalletBalance(txn, walletId, currency) {
 // prefix won't parse - hash namespace + key into a stable pseudo-uuid instead.
 const DEPOSIT_IDEMPOTENCY_NAMESPACE = 'deposit';
 const WITHDRAW_IDEMPOTENCY_NAMESPACE = 'withdraw';
+const MANUAL_ADJUSTMENT_IDEMPOTENCY_NAMESPACE = 'manual-adjustment';
 function namespacedIdempotencyKey(namespace, rawKey) {
     const hex = createHash('sha256').update(`${namespace}:${rawKey}`).digest('hex');
     return [
@@ -119,10 +174,17 @@ function toAutoWithdrawalConfigDto(row) {
         createdAt: row.createdAt.toISOString(),
     };
 }
-// The concrete settlement provider recorded per transaction: the crypto rail settles
-// through Fireblocks, the fiat rail through a PSP.
-function providerNameFor(rail) {
-    return rail === 'crypto' ? 'fireblocks' : 'psp';
+const PUBLIC_ASSET_COLUMNS = {
+    currency: walletAsset.currency,
+    network: walletAsset.network,
+    minDeposit: walletAsset.minDeposit,
+    minWithdrawal: walletAsset.minWithdrawal,
+    withdrawalFee: walletAsset.withdrawalFee,
+    depositEnabled: walletAsset.depositEnabled,
+    withdrawalEnabled: walletAsset.withdrawalEnabled,
+};
+function toWalletAssetDto(row) {
+    return serializeRow(row, { dateFields: ['createdAt', 'updatedAt'], decimalFields: [] });
 }
 /**
  * Owns all wallet balance mutations and the withdrawal review/auto-approval
@@ -136,6 +198,7 @@ export class WalletService {
     drizzle;
     events;
     payment;
+    paymentProviders;
     identityReader;
     directory;
     platformConfig;
@@ -143,10 +206,11 @@ export class WalletService {
     riskTags;
     tagEvaluationCommands;
     audit;
-    constructor({ drizzle, events, payment, directory, identityReader, platformConfig, limiter, riskTags, tagEvaluationCommands, audit, }) {
+    constructor({ drizzle, events, payment, paymentProviders, directory, identityReader, platformConfig, limiter, riskTags, tagEvaluationCommands, audit, }) {
         this.drizzle = drizzle;
         this.events = events;
         this.payment = payment;
+        this.paymentProviders = paymentProviders;
         this.directory = directory;
         this.identityReader = identityReader;
         this.platformConfig = platformConfig;
@@ -155,9 +219,36 @@ export class WalletService {
         this.tagEvaluationCommands = tagEvaluationCommands;
         this.audit = audit;
     }
+    // Every catalog row for the currency, enabled or not - resolveWithdrawalNetwork needs
+    // both to tell "never configured" from "deliberately disabled".
+    assetsForCurrency(currency) {
+        return this.drizzle.db
+            .select({
+            network: walletAsset.network,
+            minWithdrawal: walletAsset.minWithdrawal,
+            withdrawalEnabled: walletAsset.withdrawalEnabled,
+        })
+            .from(walletAsset)
+            .where(eq(walletAsset.currency, currency.toUpperCase()));
+    }
     resolveRail(currency) {
         return railFor(currency, this.platformConfig?.wallet?.cryptoCurrencies);
     }
+    // The concrete vendor a transaction/deposit-address settles through: the catalog row
+    // for the exact (currency, network) pair names the bound provider. Reconciliation
+    // scopes its diff by this column, so a null network (an unconfigured pair - no
+    // catalog row could ever match it) and a configured-but-null providerName column both
+    // resolve to the single default binding rather than leaving the column null.
+    async providerNameFor(currency, network) {
+        if (network === null) {
+            return DEFAULT_PAYMENT_PROVIDER;
+        }
+        const [row] = await this.drizzle.db
+            .select({ providerName: walletAsset.providerName })
+            .from(walletAsset)
+            .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)));
+        return row?.providerName ?? DEFAULT_PAYMENT_PROVIDER;
+    }
     rateLimit(userId) {
         return this.limiter
             ? assertRateLimit(this.limiter, `wallet-mutation:${userId}`, WALLET_MUTATION_RATE_LIMIT)
@@ -281,6 +372,117 @@ export class WalletService {
         }
         return { transactionId, status: 'completed' };
     }
+    async manualAdjust({ adminId, userId, direction, amount, currency, reason, idempotencyKey, ip, userAgent, }) {
+        const playerId = await this.identityReader.getPlayerIdByUserId(userId);
+        if (!playerId) {
+            throw new PlayerNotFoundError(userId);
+        }
+        const { result, emitted } = await this.drizzle.db.transaction(async (txn) => {
+            let walletRecord = (await txn.select().from(wallet).where(eq(wallet.userId, userId)).for('update')).at(0);
+            if (!walletRecord) {
+                if (direction === 'debit') {
+                    throw new InsufficientBalanceError('0', amount);
+                }
+                const [created] = await txn
+                    .insert(wallet)
+                    .values({ userId, currency })
+                    .onConflictDoNothing()
+                    .returning();
+                walletRecord =
+                    created ??
+                        findOneOrThrow(await txn.select().from(wallet).where(eq(wallet.userId, userId)).for('update'), new WalletNotFoundError(userId));
+            }
+            const existing = await this.findByIdempotencyKey(txn, walletRecord.id, namespacedIdempotencyKey(MANUAL_ADJUSTMENT_IDEMPOTENCY_NAMESPACE, idempotencyKey));
+            if (existing) {
+                this.assertManualAdjustmentReplayMatches(existing, {
+                    adminId,
+                    direction,
+                    amount,
+                    currency,
+                    reason,
+                });
+                return { result: { transactionId: existing.id, status: existing.status }, emitted: false };
+            }
+            const { row, replayed } = await this.insertIdempotentTransaction(txn, {
+                namespace: MANUAL_ADJUSTMENT_IDEMPOTENCY_NAMESPACE,
+                walletId: walletRecord.id,
+                rawIdempotencyKey: idempotencyKey,
+                amount,
+                currency,
+                values: {
+                    walletId: walletRecord.id,
+                    type: direction === 'credit' ? 'manual_credit' : 'manual_debit',
+                    amount,
+                    currency,
+                    status: 'completed',
+                    reviewedBy: adminId,
+                    reviewedAt: new Date(),
+                    reviewReason: reason,
+                },
+            });
+            if (replayed) {
+                this.assertManualAdjustmentReplayMatches(row, {
+                    adminId,
+                    direction,
+                    amount,
+                    currency,
+                    reason,
+                });
+                return { result: { transactionId: row.id, status: row.status }, emitted: false };
+            }
+            const balances = direction === 'credit'
+                ? await creditWalletBalance(txn, walletRecord.id, currency, amount)
+                : await debitWalletBalance(txn, walletRecord.id, currency, amount);
+            const [balance] = balances;
+            if (!balance) {
+                throw new InsufficientBalanceError(await readWalletBalance(txn, walletRecord.id, currency), amount);
+            }
+            // Derived from the row the update returned, never read separately beforehand. The
+            // wallet row is locked here but the deposit credit path does not take that lock, so
+            // a deposit can commit between a pre-read and this update - and `before` is going
+            // into an append-only audit record that cannot be corrected later.
+            const balanceBefore = direction === 'credit'
+                ? moneySubtract(balance.amount, amount)
+                : moneyAdd(balance.amount, amount);
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.manual_adjustment.created',
+                resourceType: 'wallet_transaction',
+                resourceId: row.id,
+                before: { balance: balanceBefore, currency },
+                after: {
+                    balance: balance.amount,
+                    currency,
+                    transactionId: row.id,
+                    direction,
+                    amount,
+                    reason,
+                },
+                ip,
+                userAgent,
+            });
+            return { result: { transactionId: row.id, status: row.status }, emitted: true };
+        });
+        // Every other balance-mutating path on this service emits; without this one an admin
+        // correction moves a real balance while responsible-gaming monitoring, analytics and
+        // any operator subscriber see nothing at all.
+        if (emitted) {
+            this.events.emit('wallet.manual_adjustment.created', {
+                userId,
+                playerId,
+                adminId,
+                amount,
+                currency,
+                transactionId: result.transactionId,
+                direction,
+                reason,
+                ip,
+                userAgent,
+            });
+        }
+        return result;
+    }
     // Pre-PSP replay check for deposit; also returns the resolved wallet so the transaction
     // below can skip re-selecting it. Throws IdempotencyKeyReuseError on an amount/currency mismatch.
     async findDepositReplay({ userId, idempotencyKey, amount, currency, }) {
@@ -307,6 +509,14 @@ export class WalletService {
             throw new IdempotencyKeyReuseError();
         }
     }
+    assertManualAdjustmentReplayMatches(existing, { adminId, direction, amount, currency, reason, }) {
+        if (existing.type !== (direction === 'credit' ? 'manual_credit' : 'manual_debit') ||
+            existing.reviewedBy !== adminId ||
+            existing.reviewReason !== reason) {
+            throw new IdempotencyKeyReuseError();
+        }
+        this.assertReplayMatches(existing, amount, currency);
+    }
     // Two concurrent requests with the same key can both pass the pre-insert check and race
     // on the unique index; onConflictDoNothing makes the loser's insert a no-op so it re-reads
     // the winner's committed row and returns it as a replay instead of aborting the transaction.
@@ -345,12 +555,15 @@ export class WalletService {
      * return an already-`completed`/`processing` result if the request
      * qualifies for (and passes) auto-approval - see `maybeAutoApprove`.
      */
-    async withdraw({ userId, amount, currency, idempotencyKey, destinationAddress, ip, userAgent, }) {
+    async withdraw({ userId, amount, currency, network, idempotencyKey, destinationAddress, ip, userAgent, }) {
         await this.rateLimit(userId);
         await this.assertKycForWithdrawal(userId);
         if (this.resolveRail(currency) === 'crypto' && !destinationAddress) {
             throw new DestinationAddressRequiredError();
         }
+        const assets = await this.assetsForCurrency(currency);
+        const settlementNetwork = resolveWithdrawalNetwork(assets, currency, network);
+        assertAboveMinimumWithdrawal(assets, amount, currency, settlementNetwork);
         const { transactionId, status, replayed, walletId, rail } = await this.drizzle.db.transaction(async (txn) => {
             // FOR UPDATE serializes concurrent withdrawals against a double-debit TOCTOU under READ COMMITTED.
             const current = findOneOrThrow(await txn.select().from(wallet).where(eq(wallet.userId, userId)).for('update'), new WalletNotFoundError(userId));
@@ -381,6 +594,7 @@ export class WalletService {
                     currency,
                     status: 'pending',
                     rail: this.resolveRail(currency),
+                    network: settlementNetwork,
                     destinationAddress: destinationAddress ?? null,
                 },
             });
@@ -513,6 +727,7 @@ export class WalletService {
                 username: summary?.username ?? '',
                 amount: r.tx.amount,
                 currency: r.tx.currency,
+                network: r.tx.network,
                 rail: r.tx.rail ?? null,
                 status: r.tx.status,
                 kycStatus: summary?.kycStatus ?? null,
@@ -584,6 +799,8 @@ export class WalletService {
                 rail: tx.rail,
                 adminId,
                 destinationAddress: tx.destinationAddress,
+                // Pinned at request time; without it an adapter cannot tell ERC20 USDT from TRC20.
+                network: tx.network,
             });
         }
         catch (err) {
@@ -598,7 +815,10 @@ export class WalletService {
         if (result.status !== 'completed') {
             await this.drizzle.db
                 .update(walletTransaction)
-                .set({ providerName: providerNameFor(tx.rail), providerRefId: result.externalId })
+                .set({
+                providerName: await this.providerNameFor(tx.currency, tx.network),
+                providerRefId: result.externalId,
+            })
                 .where(eq(walletTransaction.id, tx.id));
             return { transactionId: tx.id, status: 'processing' };
         }
@@ -606,7 +826,7 @@ export class WalletService {
             .update(walletTransaction)
             .set({
             status: 'completed',
-            providerName: providerNameFor(tx.rail),
+            providerName: await this.providerNameFor(tx.currency, tx.network),
             providerRefId: result.externalId,
         })
             .where(eq(walletTransaction.id, tx.id));
@@ -878,6 +1098,142 @@ export class WalletService {
             return config;
         });
     }
+    async listWalletAssets() {
+        const rows = await this.drizzle.db
+            .select()
+            .from(walletAsset)
+            .orderBy(asc(walletAsset.currency), asc(walletAsset.network));
+        return rows.map(toWalletAssetDto);
+    }
+    listEnabledWalletAssets() {
+        return this.drizzle.db
+            .select(PUBLIC_ASSET_COLUMNS)
+            .from(walletAsset)
+            .where(or(eq(walletAsset.depositEnabled, true), eq(walletAsset.withdrawalEnabled, true)))
+            .orderBy(asc(walletAsset.currency), asc(walletAsset.network));
+    }
+    async getWalletAsset(currency, network) {
+        const [row] = await this.drizzle.db
+            .select()
+            .from(walletAsset)
+            .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)));
+        return row ? toWalletAssetDto(row) : null;
+    }
+    // The catalog is operator-editable, so an admin can name a pair the bound vendor has
+    // never heard of. Reject at write time rather than at a player's deposit request.
+    assertAdapterSupports(currency, network) {
+        if (this.payment.supportsAsset && !this.payment.supportsAsset(currency, network)) {
+            throw new WalletAssetUnsupportedError();
+        }
+    }
+    // Same discipline as assertAdapterSupports, for the provider key itself: an
+    // unvalidated typo silently falls back to the default adapter, which means eg a
+    // crypto payout attempted through a PSP. Undefined (the default binding) always passes.
+    assertProviderNameValid(providerName) {
+        if (providerName !== undefined && !this.paymentProviders.names().includes(providerName)) {
+            throw new WalletAssetUnknownProviderError();
+        }
+    }
+    async createWalletAsset(adminId, input, meta) {
+        this.assertAdapterSupports(input.currency, input.network);
+        this.assertProviderNameValid(input.providerName);
+        return this.drizzle.db.transaction(async (txn) => {
+            const rows = await txn.insert(walletAsset).values(input).onConflictDoNothing().returning();
+            // Empty => the (currency, network) unique index rejected it.
+            const asset = toWalletAssetDto(findOneOrThrow(rows, new WalletAssetAlreadyExistsError()));
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.wallet_asset.created',
+                resourceType: 'wallet_asset',
+                resourceId: asset.id,
+                before: null,
+                after: asset,
+                ...meta,
+            });
+            return asset;
+        });
+    }
+    // Deliberately touches only the catalog row: a withdrawal already pending or processing
+    // in this currency keeps its own terms and is never cancelled by disabling the pair.
+    async updateWalletAsset(adminId, { currency, network, ...changes }, meta) {
+        if (changes.providerAssetId !== undefined) {
+            this.assertAdapterSupports(currency, network);
+        }
+        return this.drizzle.db.transaction(async (txn) => {
+            const [before] = await txn
+                .select()
+                .from(walletAsset)
+                .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)));
+            if (!before) {
+                throw new WalletAssetNotFoundError(`${currency}/${network}`);
+            }
+            const rows = await txn
+                .update(walletAsset)
+                .set(changes)
+                .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)))
+                .returning();
+            const asset = toWalletAssetDto(findOneOrThrow(rows, new WalletAssetNotFoundError(`${currency}/${network}`)));
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.wallet_asset.updated',
+                resourceType: 'wallet_asset',
+                resourceId: asset.id,
+                before: toWalletAssetDto(before),
+                after: asset,
+                ...meta,
+            });
+            return asset;
+        });
+    }
+    async deleteWalletAsset(adminId, currency, network, meta) {
+        return this.drizzle.db.transaction(async (txn) => {
+            const [before] = await txn
+                .select()
+                .from(walletAsset)
+                .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)));
+            if (!before) {
+                return false;
+            }
+            // wallet_balance is keyed by currency only (no network column), so this guard is
+            // necessarily currency-wide: removing one network of a currency players still hold
+            // is blocked even if their balance arrived over another network. Fails safe.
+            const [held] = await txn
+                .select({ n: count() })
+                .from(walletBalance)
+                .where(and(eq(walletBalance.currency, currency), sql `${walletBalance.amount} > 0`));
+            if ((held?.n ?? 0) > 0) {
+                throw new WalletAssetInUseError();
+            }
+            // Renaming a pair is a delete plus a create (the (currency, network) key AND
+            // providerName are immutable), so this delete is the only way providerName ever
+            // effectively changes. Block it while a pending/processing transaction exists for
+            // this exact (currency, network) pair - otherwise the vendor reference an in-flight
+            // payout is settling through gets rewritten out from under it.
+            const [inFlight] = await txn
+                .select({ n: count() })
+                .from(walletTransaction)
+                .where(and(eq(walletTransaction.currency, currency), eq(walletTransaction.network, network), inArray(walletTransaction.status, ['pending', 'processing'])));
+            if ((inFlight?.n ?? 0) > 0) {
+                throw new WalletAssetHasInFlightTransactionsError();
+            }
+            await txn
+                .delete(walletAsset)
+                .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)));
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.wallet_asset.deleted',
+                resourceType: 'wallet_asset',
+                resourceId: before.id,
+                before: toWalletAssetDto(before),
+                after: null,
+                ...meta,
+            });
+            return true;
+        });
+    }
     async autoApprovalKycStatus(userId) {
         // No directory bound => cannot verify KYC => fail closed.
         if (!this.directory) {
@@ -1001,7 +1357,7 @@ export class WalletService {
         });
         return { transactionId: tx.id, status: 'rejected' };
     }
-    async getTransactions({ userId, page, limit, sortBy, sortOrder, }) {
+    async getTransactions({ userId, page, limit, sortBy, sortOrder, includeInternal = false, }) {
         const db = this.drizzle.db;
         const [walletRecord] = await db.select().from(wallet).where(eq(wallet.userId, userId));
         if (!walletRecord) {
@@ -1035,8 +1391,12 @@ export class WalletService {
                 type: tx.type,
                 amount: tx.amount,
                 currency: tx.currency,
+                network: tx.network,
                 status: tx.status,
                 createdAt: tx.createdAt.toISOString(),
+                reviewedBy: includeInternal ? tx.reviewedBy : null,
+                reviewedAt: includeInternal ? (tx.reviewedAt?.toISOString() ?? null) : null,
+                reviewReason: includeInternal ? tx.reviewReason : null,
             })),
             total: Number(n),
             page,
@@ -1060,7 +1420,7 @@ export class WalletService {
             network: network ?? null,
             address: issued.address,
             tag: issued.tag ?? null,
-            providerName: providerNameFor(this.resolveRail(currency)),
+            providerName: await this.providerNameFor(currency, network ?? null),
         })
             .onConflictDoNothing()
             .returning();
@@ -1103,6 +1463,9 @@ export class WalletService {
                 currency: event.currency,
                 status: 'completed',
                 rail: this.resolveRail(event.currency),
+                // Prefer the chain the vendor reported; fall back to the one the address was
+                // issued on, which is the only network an address-only webhook can imply.
+                network: event.network ?? depositAddress.network,
                 providerName: depositAddress.providerName,
                 providerRefId: event.externalId,
                 destinationAddress: event.address,