@openora/core 0.4.0 → 0.4.1-canary.100

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

@@ -1,32 +1,182 @@
-import { makeNotFoundError, makeConflictError, createDomainError, findOneOrThrow, pageToOffset, withAdvisoryXactLock, assertRateLimit, createLogger, } from '@openora/core/server';
-import { eq, desc, sql, and, gte, lte, count, inArray } from 'drizzle-orm';
+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, walletTransaction, autoWithdrawalRule, } from '../schema/index.js';
+import { wallet, walletBalance, walletTransaction, autoWithdrawalRule, walletAutoWithdrawalConfig, walletDepositAddress, walletBonusCredit, walletBonusRolloverConfig, walletWithdrawalAddress, walletAsset, } from '../schema/index.js';
+import { LIVE_WEBHOOK_RUN_ID, recordReconciliationFinding, } from './reconciliation-finding.service.js';
 const logger = createLogger('wallet');
 export const WalletNotFoundError = makeNotFoundError('Wallet');
 export const WithdrawalNotFoundError = makeNotFoundError('Withdrawal');
+export const AutoWithdrawalConfigNotFoundError = makeNotFoundError('AutoWithdrawalConfig');
+export const BonusRolloverConfigNotFoundError = makeNotFoundError('BonusRolloverConfig');
+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');
-// Statuses that satisfy the withdrawal KYC gate.
-const KYC_PASS_STATUSES = new Set(['verified', 'manually_overridden']);
-export const CurrencyMismatchError = createDomainError('CurrencyMismatchError', (requested, walletCurrency) => `Currency mismatch: requested ${requested}, wallet holds ${walletCurrency}`);
-// 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.
-const CRYPTO_CURRENCIES = new Set(['BTC', 'ETH', 'USDT']);
+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 BonusRolloverLockedError = createDomainError('BonusRolloverLockedError', (locked) => `Withdrawal blocked: ${locked} is locked by an active bonus rollover requirement`);
+export const DestinationAddressNotWhitelistedError = makeConflictError('DestinationAddressNotWhitelistedError', 'This payout address is not approved for withdrawals. Save it in your address book first');
+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 WithdrawalAddressAlreadyExistsError = makeConflictError('WithdrawalAddressAlreadyExistsError', 'This address is already saved for that currency and network');
+export const WithdrawalAddressLimitReachedError = createDomainError('WithdrawalAddressLimitReachedError', (limit) => `A player may save at most ${limit} withdrawal addresses`);
+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 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 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']);
+// A saved-address book, not a payout allowlist: the cap only stops one account turning
+// the table into unbounded free storage. Not operator-configurable until someone asks.
+const WITHDRAWAL_ADDRESS_LIMIT = 50;
+function toWithdrawalAddressDto(row) {
+    return {
+        id: row.id,
+        label: row.label,
+        currency: row.currency,
+        network: row.network,
+        address: row.address,
+        createdAt: row.createdAt.toISOString(),
+    };
+}
+// 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.
+const DEFAULT_WALLET_CURRENCY = 'USD';
 // Per-user throttle on money mutations - guards a runaway/misbehaving client, not
 // 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 };
-export function railFor(currency) {
-    return CRYPTO_CURRENCIES.has(currency.toUpperCase()) ? 'crypto' : 'fiat';
+/**
+ * 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()))
+        : DEFAULT_CRYPTO_CURRENCIES;
+    return set.has(currency.toUpperCase()) ? 'crypto' : 'fiat';
+}
+// Currency checks elsewhere are case-insensitive, so `usd` reaches here for a `USD`
+// wallet. Every read and write of wallet_balance funnels through these three helpers,
+// so normalizing the key here is enough to keep one row per wallet+currency.
+export const balanceKey = (currency) => currency.toUpperCase();
+export function creditWalletBalance(txn, walletId, currency, amount) {
+    return txn
+        .insert(walletBalance)
+        .values({ walletId, currency: balanceKey(currency), amount })
+        .onConflictDoUpdate({
+        target: [walletBalance.walletId, walletBalance.currency],
+        set: {
+            amount: sql `${walletBalance.amount} + ${amount}::numeric`,
+            updatedAt: new Date(),
+        },
+    })
+        .returning({ amount: walletBalance.amount });
+}
+export function debitWalletBalance(txn, walletId, currency, amount) {
+    return txn
+        .update(walletBalance)
+        .set({ amount: sql `${walletBalance.amount} - ${amount}::numeric` })
+        .where(and(eq(walletBalance.walletId, walletId), eq(walletBalance.currency, balanceKey(currency)), gte(walletBalance.amount, amount)))
+        .returning({ amount: walletBalance.amount });
+}
+export async function readWalletBalance(txn, walletId, currency) {
+    const [row] = await txn
+        .select({ amount: walletBalance.amount })
+        .from(walletBalance)
+        .where(and(eq(walletBalance.walletId, walletId), eq(walletBalance.currency, balanceKey(currency))));
+    return row?.amount ?? '0';
+}
+export function debitWithdrawableBalance(txn, walletId, currency, amount) {
+    const currencyKey = balanceKey(currency);
+    return txn
+        .update(walletBalance)
+        .set({ amount: sql `${walletBalance.amount} - ${amount}::numeric` })
+        .where(and(eq(walletBalance.walletId, walletId), eq(walletBalance.currency, currencyKey), gte(sql `${walletBalance.amount} - COALESCE((
+            SELECT SUM(
+              ${walletBonusCredit.creditedAmount}
+              * GREATEST(
+                ${walletBonusCredit.rolloverRequired} - ${walletBonusCredit.rolloverProgress},
+                0
+              )
+              / NULLIF(${walletBonusCredit.rolloverRequired}, 0)
+            )
+            FROM ${walletBonusCredit}
+            WHERE ${walletBonusCredit.walletId} = ${walletId}
+              AND ${walletBonusCredit.currency} = ${currencyKey}
+              AND ${walletBonusCredit.status} = 'active'
+          ), 0)`, amount)))
+        .returning({ amount: walletBalance.amount });
+}
+async function readLockedBonusAmount(txn, walletId, currency) {
+    const currencyKey = balanceKey(currency);
+    const [row] = await txn
+        .select({
+        locked: sql `coalesce(sum(
+        ${walletBonusCredit.creditedAmount}
+        * greatest(${walletBonusCredit.rolloverRequired} - ${walletBonusCredit.rolloverProgress}, 0)
+        / nullif(${walletBonusCredit.rolloverRequired}, 0)
+      ), 0)`,
+    })
+        .from(walletBonusCredit)
+        .where(and(eq(walletBonusCredit.walletId, walletId), eq(walletBonusCredit.currency, currencyKey), eq(walletBonusCredit.status, 'active')));
+    return row?.locked ?? '0';
 }
 // Namespace the key per operation so the same raw key on a deposit then a withdraw can't
 // collide on the (walletId, idempotencyKey) unique index. The column is a uuid, so a string
 // 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 [
@@ -39,72 +189,201 @@ function namespacedIdempotencyKey(namespace, rawKey) {
 }
 // ponytail: a flat, currency-agnostic threshold - a starter heuristic for the review
 // queue, not a compliance risk engine. Revisit with a real risk service if/when one exists.
-const LARGE_WITHDRAWAL_THRESHOLD = 5000;
+// moneyToNumber is the sanctioned JS conversion point for this heuristic comparison only.
+const LARGE_WITHDRAWAL_THRESHOLD = '5000';
 // ponytail: >=3 withdrawals in a 24h window flags velocity; a flat count, not a per-tier rule.
 const HIGH_FREQUENCY_WINDOW_MS = 24 * 60 * 60 * 1000;
 const HIGH_FREQUENCY_MIN_COUNT = 3;
 const DAILY_CAP_WINDOW_MS = 24 * 60 * 60 * 1000;
 // Also the marker the cumulative-cap query reads back to identify auto-approved payouts - keep write and read in lockstep.
 const AUTO_APPROVED_REASON = 'auto-approved';
+function toDepositAddressResult(row) {
+    return {
+        address: row.address,
+        currency: row.currency,
+        ...(row.network === null ? {} : { network: row.network }),
+        ...(row.tag === null ? {} : { tag: row.tag }),
+    };
+}
 function toAutoWithdrawalRuleDto(row) {
     return {
         id: row.id,
         userId: row.userId,
-        threshold: Number(row.threshold),
+        threshold: row.threshold,
         reason: row.reason,
         createdBy: row.createdBy,
         createdAt: row.createdAt.toISOString(),
         updatedAt: row.updatedAt.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';
+function toAutoWithdrawalConfigDto(row) {
+    return {
+        id: row.id,
+        fiatThreshold: row.fiatThreshold,
+        cryptoThreshold: row.cryptoThreshold,
+        excludeRiskFlags: row.excludeRiskFlags,
+        updatedBy: row.updatedBy,
+        updatedAt: row.updatedAt.toISOString(),
+        createdAt: row.createdAt.toISOString(),
+    };
 }
+function toBonusCreditDto(row) {
+    return {
+        id: row.id,
+        currency: row.currency,
+        sourceType: row.sourceType,
+        creditedAmount: row.creditedAmount,
+        rolloverMultiplier: row.rolloverMultiplier,
+        rolloverRequired: row.rolloverRequired,
+        rolloverProgress: row.rolloverProgress,
+        status: row.status,
+        createdAt: row.createdAt.toISOString(),
+        completedAt: row.completedAt ? row.completedAt.toISOString() : null,
+    };
+}
+function toBonusRolloverConfigDto(row) {
+    return {
+        id: row.id,
+        multiplier: row.multiplier,
+        updatedAt: row.updatedAt.toISOString(),
+    };
+}
+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
+ * pipeline. Every balance change is a transactional, idempotent-keyed ledger
+ * write (never a bare balance update) - `amount` is always a decimal string,
+ * mutated via SQL numeric arithmetic, never a JS float. Domain events emit only
+ * AFTER the owning transaction commits, and only for the non-replay branch of
+ * an idempotent call.
+ */
 export class WalletService {
     drizzle;
     events;
     payment;
+    paymentProviders;
+    identityReader;
     directory;
     platformConfig;
     limiter;
     riskTags;
+    tagEvaluationCommands;
     audit;
-    constructor({ drizzle, events, payment, directory, platformConfig, limiter, riskTags, 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;
         this.limiter = limiter;
         this.riskTags = riskTags;
+        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)
             : Promise.resolve();
     }
-    /** Fail-closed KYC gate: when enabled, a withdrawal needs a passing status (verified|manually_overridden). */
     async assertKycForWithdrawal(userId) {
-        if (!this.platformConfig?.kyc?.gateWithdrawals)
+        if (!this.platformConfig?.kyc?.gateWithdrawals) {
             return;
+        }
         const status = await this.autoApprovalKycStatus(userId);
-        if (!status || !KYC_PASS_STATUSES.has(status)) {
+        if (!status || !KYC_PASS_STATUSES.has(normalizeKycStatus(status))) {
             throw new KycRequiredError();
         }
     }
     async getBalance(userId) {
         const [record] = await this.drizzle.db.select().from(wallet).where(eq(wallet.userId, userId));
         if (!record) {
-            return { balance: 0, currency: 'USD' };
+            return { balance: '0', currency: DEFAULT_WALLET_CURRENCY };
         }
         return {
-            balance: Number(record.balance),
+            balance: await readWalletBalance(this.drizzle.db, record.id, record.currency),
             currency: record.currency,
         };
     }
+    async getBalances(userId) {
+        const [record] = await this.drizzle.db.select().from(wallet).where(eq(wallet.userId, userId));
+        if (!record) {
+            return { activeCurrency: DEFAULT_WALLET_CURRENCY, balances: [] };
+        }
+        const rows = await this.drizzle.db
+            .select({ currency: walletBalance.currency, balance: walletBalance.amount })
+            .from(walletBalance)
+            .where(eq(walletBalance.walletId, record.id))
+            .orderBy(walletBalance.currency);
+        return { activeCurrency: record.currency, balances: rows };
+    }
+    // TODO: validate `currency` against a canonical supported-currency list once one
+    // exists - `platformConfig.wallet.cryptoCurrencies` classifies rails, it is not an
+    // allowlist, so today any non-empty string is accepted and persisted.
+    async setActiveCurrency(userId, currency) {
+        const updated = await this.drizzle.db
+            .update(wallet)
+            .set({ currency })
+            .where(eq(wallet.userId, userId))
+            .returning({ currency: wallet.currency });
+        const record = updated[0];
+        if (!record) {
+            throw new WalletNotFoundError(userId);
+        }
+        return { activeCurrency: record.currency };
+    }
+    /**
+     * `idempotencyKey` (when supplied) makes a retried deposit a no-op: a replay
+     * returns the original committed result WITHOUT calling the PSP again or
+     * crediting the balance twice, and rejects if the same key is reused with a
+     * different amount/currency (`IdempotencyKeyReuseError`). A GENUINE
+     * concurrent race (two first-attempts, same key, landing at once) can both
+     * reach the PSP, but the ledger insert's unique-index conflict still
+     * guarantees only one balance credit - the loser's write becomes a replay
+     * read of the winner's row.
+     */
     async deposit({ userId, amount, currency, provider, idempotencyKey, }) {
         await this.rateLimit(userId);
         // Short-circuit a replay BEFORE the PSP call - the common retry case (client
@@ -114,10 +393,17 @@ export class WalletService {
         let preResolvedWallet;
         if (idempotencyKey) {
             const found = await this.findDepositReplay({ userId, idempotencyKey, amount, currency });
-            if (found.replay)
+            if (found.replay) {
                 return found.replay;
+            }
             preResolvedWallet = found.walletRecord;
         }
+        else {
+            [preResolvedWallet] = await this.drizzle.db
+                .select()
+                .from(wallet)
+                .where(eq(wallet.userId, userId));
+        }
         const psp = await this.payment.processDeposit(amount, currency, { userId, provider });
         const { transactionId, replayed } = await this.drizzle.db.transaction(async (txn) => {
             let walletRecord = preResolvedWallet;
@@ -125,10 +411,7 @@ export class WalletService {
                 [walletRecord] = await txn.select().from(wallet).where(eq(wallet.userId, userId));
             }
             if (!walletRecord) {
-                [walletRecord] = await txn
-                    .insert(wallet)
-                    .values({ userId, balance: '0', currency })
-                    .returning();
+                walletRecord = findOneOrThrow(await txn.insert(wallet).values({ userId, currency }).returning(), new WalletNotFoundError(userId));
             }
             const { row, replayed } = await this.insertIdempotentTransaction(txn, {
                 namespace: DEPOSIT_IDEMPOTENCY_NAMESPACE,
@@ -139,27 +422,141 @@ export class WalletService {
                 values: {
                     walletId: walletRecord.id,
                     type: 'deposit',
-                    amount: amount.toString(),
+                    amount,
                     currency,
                     status: 'completed',
-                    rail: railFor(currency),
+                    rail: this.resolveRail(currency),
                     providerName: provider,
                     providerRefId: psp.externalId,
                 },
             });
             if (!replayed) {
-                await txn
-                    .update(wallet)
-                    .set({ balance: sql `${wallet.balance} + ${amount}` })
-                    .where(eq(wallet.id, walletRecord.id));
+                await creditWalletBalance(txn, walletRecord.id, currency, amount);
             }
             return { transactionId: row.id, replayed };
         });
         if (!replayed) {
-            this.events.emit('wallet.deposit.completed', { userId, amount, currency, transactionId });
+            this.events.emit('wallet.deposit.completed', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                amount,
+                currency,
+                transactionId,
+            });
         }
         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, }) {
@@ -167,20 +564,33 @@ export class WalletService {
             .select()
             .from(wallet)
             .where(eq(wallet.userId, userId));
-        if (!walletRecord)
+        if (!walletRecord) {
             return { walletRecord: undefined, replay: undefined };
+        }
         const existing = await this.findByIdempotencyKey(this.drizzle.db, walletRecord.id, namespacedIdempotencyKey(DEPOSIT_IDEMPOTENCY_NAMESPACE, idempotencyKey));
-        if (!existing)
+        if (!existing) {
             return { walletRecord, replay: undefined };
+        }
         this.assertReplayMatches(existing, amount, currency);
         return { walletRecord, replay: { transactionId: existing.id, status: existing.status } };
     }
+    // Replay comparison only (not a ledger write). moneyEquals avoids a false mismatch between
+    // an unnormalized caller string (eg "10") and the DB's fixed-scale value ("10.00") while
+    // staying exact - a float compare would let two amounts differing past the 15th digit pass.
     assertReplayMatches(existing, amount, currency) {
-        if (Number(existing.amount) !== amount ||
+        if (!moneyEquals(existing.amount, amount) ||
             existing.currency.toUpperCase() !== currency.toUpperCase()) {
             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.
@@ -194,8 +604,9 @@ export class WalletService {
         const [row] = idempotencyKey
             ? await insertQuery.onConflictDoNothing().returning()
             : await insertQuery.returning();
-        if (row)
+        if (row) {
             return { row, replayed: false };
+        }
         // Only the keyed (onConflictDoNothing) branch above can return an empty `returning()`
         // - the plain-insert branch always yields exactly one row.
         if (!idempotencyKey) {
@@ -208,17 +619,29 @@ export class WalletService {
         this.assertReplayMatches(winner, amount, currency);
         return { row: winner, replayed: true };
     }
-    /** Creates a PENDING withdrawal and HOLDS the funds (balance debited at request time). Funds are returned on reject/PSP-failure. */
-    async withdraw({ userId, amount, currency, idempotencyKey, }) {
+    /**
+     * Creates a PENDING withdrawal and HOLDS the funds immediately (balance
+     * debited at request time, not on approval) - funds are returned on
+     * reject/PSP-failure. The debit is a conditional `UPDATE ... WHERE balance
+     * >= amount`, atomic with the row lock (`FOR UPDATE`) taken on the wallet,
+     * so two concurrent withdrawals can't both pass a balance check and
+     * double-spend. `idempotencyKey` replay semantics mirror `deposit()`. May
+     * return an already-`completed`/`processing` result if the request
+     * qualifies for (and passes) auto-approval - see `maybeAutoApprove`.
+     */
+    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 destinationWalletId = await this.requireWhitelistedWalletId(userId, currency, settlementNetwork, destinationAddress);
         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));
-            // Single-currency wallet: reject a mismatch rather than coerce it onto the wrong rail.
-            if (currency.toUpperCase() !== current.currency.toUpperCase()) {
-                throw new CurrencyMismatchError(currency, current.currency);
-            }
             // Replay of an already-committed key: return the original untouched. The new-key race is caught by the insert below.
             if (idempotencyKey) {
                 const existing = await this.findByIdempotencyKey(txn, current.id, namespacedIdempotencyKey(WITHDRAW_IDEMPOTENCY_NAMESPACE, idempotencyKey));
@@ -229,7 +652,7 @@ export class WalletService {
                         status: existing.status,
                         replayed: true,
                         walletId: current.id,
-                        rail: railFor(currency),
+                        rail: this.resolveRail(currency),
                     };
                 }
             }
@@ -242,10 +665,13 @@ export class WalletService {
                 values: {
                     walletId: current.id,
                     type: 'withdrawal',
-                    amount: amount.toString(),
+                    amount,
                     currency,
                     status: 'pending',
-                    rail: railFor(currency),
+                    rail: this.resolveRail(currency),
+                    network: settlementNetwork,
+                    destinationAddress: destinationAddress ?? null,
+                    destinationWalletId,
                 },
             });
             if (replayed) {
@@ -254,29 +680,43 @@ export class WalletService {
                     status: row.status,
                     replayed,
                     walletId: current.id,
-                    rail: railFor(currency),
+                    rail: this.resolveRail(currency),
                 };
             }
-            // Guarded conditional debit: the WHERE makes balance>=amount atomic with the write; 0 rows back rolls back the whole tx.
-            const debited = await txn
-                .update(wallet)
-                .set({ balance: sql `${wallet.balance} - ${amount}` })
-                .where(and(eq(wallet.id, current.id), gte(wallet.balance, amount.toString())))
-                .returning({ id: wallet.id });
+            const debited = await debitWithdrawableBalance(txn, current.id, currency, amount);
             if (debited.length !== 1) {
-                throw new InsufficientBalanceError(Number(current.balance), amount);
+                const [available, locked] = await Promise.all([
+                    readWalletBalance(txn, current.id, currency),
+                    readLockedBonusAmount(txn, current.id, currency),
+                ]);
+                if (moneyToNumber(available) < moneyToNumber(amount)) {
+                    throw new InsufficientBalanceError(available, amount);
+                }
+                throw new BonusRolloverLockedError(locked);
+            }
+            if (this.tagEvaluationCommands) {
+                await this.tagEvaluationCommands.evaluateWithdrawalRequested(txn, { userId, amount });
             }
             return {
                 transactionId: row.id,
                 status: row.status,
                 replayed,
                 walletId: current.id,
-                rail: railFor(currency),
+                rail: this.resolveRail(currency),
             };
         });
-        if (replayed)
+        if (replayed) {
             return { transactionId, status };
-        this.events.emit('wallet.withdrawal.requested', { userId, amount, currency, transactionId });
+        }
+        this.events.emit('wallet.withdrawal.requested', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            amount,
+            currency,
+            transactionId,
+            ip: ip ?? null,
+            userAgent: userAgent ?? null,
+        });
         // Fail-closed post-step: decides who approves (system vs manual queue), never throws out of withdraw() - failure leaves the row pending.
         const auto = await this.maybeAutoApprove({
             userId,
@@ -292,17 +732,20 @@ export class WalletService {
         const db = this.drizzle.db;
         const { page, limit } = filters;
         const conditions = [eq(walletTransaction.type, 'withdrawal')];
-        if (filters.status)
+        if (filters.status) {
             conditions.push(eq(walletTransaction.status, filters.status));
-        if (filters.currency)
+        }
+        if (filters.currency) {
             conditions.push(eq(walletTransaction.currency, filters.currency));
-        if (filters.rail)
+        }
+        if (filters.rail) {
             conditions.push(eq(walletTransaction.rail, filters.rail));
+        }
         if (filters.minAmount !== undefined) {
-            conditions.push(gte(walletTransaction.amount, filters.minAmount.toString()));
+            conditions.push(gte(walletTransaction.amount, filters.minAmount));
         }
         if (filters.maxAmount !== undefined) {
-            conditions.push(lte(walletTransaction.amount, filters.maxAmount.toString()));
+            conditions.push(lte(walletTransaction.amount, filters.maxAmount));
         }
         if (filters.dateFrom) {
             conditions.push(gte(walletTransaction.createdAt, new Date(filters.dateFrom)));
@@ -312,19 +755,40 @@ export class WalletService {
         }
         // Bounded queue: fetch all SQL-matching rows, then enrich + kycStatus-filter + paginate in memory,
         // else DB-side pagination makes `total` wrong once kycStatus prunes.
+        const wdSortBy = filters.sortBy ?? 'createdAt';
+        const wdDir = (filters.sortOrder ?? 'desc') === 'asc' ? asc : desc;
+        const WD_SORT_COLS = {
+            createdAt: walletTransaction.createdAt,
+            amount: walletTransaction.amount,
+            status: walletTransaction.status,
+            currency: walletTransaction.currency,
+            rail: walletTransaction.rail,
+            reviewedAt: walletTransaction.reviewedAt,
+        };
         const rows = await db
             .select({ tx: walletTransaction, userId: wallet.userId })
             .from(walletTransaction)
             .innerJoin(wallet, eq(wallet.id, walletTransaction.walletId))
             .where(and(...conditions))
-            .orderBy(desc(walletTransaction.createdAt));
+            .orderBy(wdDir(WD_SORT_COLS[wdSortBy]), desc(walletTransaction.id));
         const userIds = [...new Set(rows.map((r) => r.userId))];
         const summaries = this.directory ? await this.directory.lookupPlayers(userIds) : [];
         const byUserId = new Map(summaries.map((s) => [s.userId, s]));
-        const matching = filters.kycStatus
-            ? rows.filter((r) => byUserId.get(r.userId)?.kycStatus === filters.kycStatus)
+        // Normalize both sides before comparing: the ADMIN_USER_DIRECTORY port's return type
+        // still permits the deprecated `verified` value (it aliases `approved`), and this
+        // module cannot assume every bound implementation already normalized it at its own
+        // read boundary - a raw `===` here would silently hide every legacy-verified player
+        // from the queue the moment an admin filters by the canonical `approved`.
+        const kycStatusFilter = filters.kycStatus ? normalizeKycStatus(filters.kycStatus) : undefined;
+        const matching = kycStatusFilter
+            ? rows.filter((r) => {
+                const kycStatus = byUserId.get(r.userId)?.kycStatus;
+                return kycStatus !== undefined && kycStatus !== null
+                    ? normalizeKycStatus(kycStatus) === kycStatusFilter
+                    : false;
+            })
             : rows;
-        const start = (page - 1) * limit;
+        const start = pageToOffset(page, limit);
         const pageRows = matching.slice(start, start + limit);
         // One batched velocity query for the page (no N+1); shares the window + threshold + query the auto-approval evaluator uses.
         const pageWalletIds = [...new Set(pageRows.map((r) => r.tx.walletId))];
@@ -332,21 +796,27 @@ export class WalletService {
         const items = pageRows.map((r) => {
             const summary = byUserId.get(r.userId);
             const riskTags = [];
-            if (Number(r.tx.amount) >= LARGE_WITHDRAWAL_THRESHOLD)
+            if (moneyToNumber(r.tx.amount) >= moneyToNumber(LARGE_WITHDRAWAL_THRESHOLD)) {
                 riskTags.push('large_amount');
-            if (frequentWalletIds.has(r.tx.walletId))
+            }
+            if (frequentWalletIds.has(r.tx.walletId)) {
                 riskTags.push('high_frequency');
+            }
             return {
                 transactionId: r.tx.id,
                 userId: r.userId,
+                playerId: summary?.playerId ?? null,
                 username: summary?.username ?? '',
-                amount: Number(r.tx.amount),
+                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,
                 riskTags,
                 requestedAt: r.tx.createdAt.toISOString(),
+                destinationAddress: r.tx.destinationAddress,
+                txHash: r.tx.txHash,
             };
         });
         return { items, total: matching.length, page, limit };
@@ -356,11 +826,11 @@ export class WalletService {
      * or Failed + refund on PSP error. Robust PSP idempotency-key/reconciliation for a
      * lost-response is deferred - same scope boundary the deposit path declares.
      */
-    async approveWithdrawal(adminId, withdrawalId) {
+    async approveWithdrawal(adminId, withdrawalId, meta) {
         // Two-phase: commit the `processing` flip first (FOR UPDATE lock), then call the PSP OUTSIDE
         // the tx (a failure refunds in a second tx). Never inline the PSP call inside the hold transaction.
         const tx = await this.drizzle.db.transaction((txn) => this.flipToProcessing({ txn, withdrawalId, adminId }));
-        return this.settleApproved(tx, adminId);
+        return this.settleApproved(tx, adminId, meta);
     }
     // Phase one: the pending -> processing flip under a FOR UPDATE lock. Extracted so the auto path can run it
     // inside its advisory-locked cap-check transaction, committing the marker atomically. Never call the PSP here.
@@ -374,7 +844,7 @@ export class WalletService {
         if (current.status !== 'pending' || current.type !== 'withdrawal') {
             throw new WithdrawalNotPendingError();
         }
-        const [updated] = await txn
+        return findOneOrThrow(await txn
             .update(walletTransaction)
             .set({
             status: 'processing',
@@ -383,14 +853,13 @@ export class WalletService {
             ...(reviewReason !== undefined ? { reviewReason } : {}),
         })
             .where(eq(walletTransaction.id, withdrawalId))
-            .returning();
-        return updated;
+            .returning(), new WithdrawalNotFoundError(withdrawalId));
     }
     // Phase two: settle a `processing` withdrawal via the PSP (Completed on success, Failed + refund on error).
     // Runs OUTSIDE the hold/flip transaction so the external PSP call never holds a DB lock.
-    async settleApproved(tx, adminId) {
+    async settleApproved(tx, adminId, meta) {
         const userId = await this.userIdForWallet(tx.walletId);
-        const amount = Number(tx.amount);
+        const amount = tx.amount;
         // approved/failed are admin-attributed events (schema requires a uuid adminId); the system auto path
         // skips them - its trail is the AUDIT_WRITER entry plus the shared `completed` event below.
         if (adminId) {
@@ -400,6 +869,8 @@ export class WalletService {
                 currency: tx.currency,
                 transactionId: tx.id,
                 adminId,
+                ip: meta?.ip ?? null,
+                userAgent: meta?.userAgent ?? null,
             });
         }
         let result;
@@ -409,67 +880,133 @@ export class WalletService {
                 userId,
                 rail: tx.rail,
                 adminId,
+                destinationAddress: tx.destinationAddress,
+                // The provider-side whitelisted destination for that address, when the bound adapter
+                // whitelists at all. Absent for an address that predates whitelisting or was never in
+                // the book, and such an adapter is expected to refuse rather than pay out to the raw
+                // address - the whitelist is the control, so bypassing it would defeat the point.
+                ...(tx.destinationWalletId ? { destinationWalletId: tx.destinationWalletId } : {}),
+                // Pinned at request time; without it an adapter cannot tell ERC20 USDT from TRC20.
+                network: tx.network,
             });
         }
         catch (err) {
             // Payout did not happen - mark failed and return the held funds in one transaction.
-            await this.drizzle.db.transaction(async (txn) => {
-                await txn
-                    .update(walletTransaction)
-                    .set({ status: 'failed' })
-                    .where(eq(walletTransaction.id, tx.id));
-                await txn
-                    .update(wallet)
-                    .set({ balance: sql `${wallet.balance} + ${amount}` })
-                    .where(eq(wallet.id, tx.walletId));
-            });
-            if (adminId) {
-                this.events.emit('wallet.withdrawal.failed', {
-                    userId,
-                    amount,
-                    currency: tx.currency,
-                    transactionId: tx.id,
-                    adminId,
-                });
-            }
+            await this.finalizeFailedWithdrawal({ tx, adminId, userId, amount });
             throw err;
         }
+        if (result.status === 'failed') {
+            await this.finalizeFailedWithdrawal({ tx, adminId, userId, amount });
+            return { transactionId: tx.id, status: 'failed' };
+        }
+        if (result.status !== 'completed') {
+            await this.drizzle.db
+                .update(walletTransaction)
+                .set({
+                providerName: await this.providerNameFor(tx.currency, tx.network),
+                providerRefId: result.externalId,
+            })
+                .where(eq(walletTransaction.id, tx.id));
+            return { transactionId: tx.id, status: 'processing' };
+        }
         await this.drizzle.db
             .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));
         this.events.emit('wallet.withdrawal.completed', {
             userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
             amount,
             currency: tx.currency,
             transactionId: tx.id,
         });
         return { transactionId: tx.id, status: 'completed' };
     }
+    async finalizeFailedWithdrawal({ tx, adminId, userId, amount, }) {
+        const transitioned = await this.drizzle.db.transaction(async (txn) => {
+            const updated = await txn
+                .update(walletTransaction)
+                .set({ status: 'failed' })
+                .where(and(eq(walletTransaction.id, tx.id), eq(walletTransaction.status, 'processing')))
+                .returning({ id: walletTransaction.id });
+            if (updated.length === 0) {
+                return false;
+            }
+            await creditWalletBalance(txn, tx.walletId, tx.currency, amount);
+            return true;
+        });
+        if (transitioned && adminId) {
+            this.events.emit('wallet.withdrawal.failed', {
+                userId,
+                amount,
+                currency: tx.currency,
+                transactionId: tx.id,
+                adminId,
+            });
+        }
+    }
+    async reconcileWithdrawalStatus(event) {
+        const { externalId, status, txHash } = event;
+        const [tx] = await this.drizzle.db
+            .select()
+            .from(walletTransaction)
+            .where(eq(walletTransaction.providerRefId, externalId));
+        if (!tx || tx.type !== 'withdrawal') {
+            logger.warn({ externalId }, 'payment webhook: no matching withdrawal for providerRefId');
+            return;
+        }
+        if (tx.status !== 'processing') {
+            return;
+        }
+        const userId = await this.userIdForWallet(tx.walletId);
+        if (status === 'completed') {
+            const updated = await this.drizzle.db
+                .update(walletTransaction)
+                .set({ status: 'completed', txHash: txHash ?? tx.txHash })
+                .where(and(eq(walletTransaction.id, tx.id), eq(walletTransaction.status, 'processing')))
+                .returning({ id: walletTransaction.id });
+            if (updated.length === 0) {
+                return;
+            }
+            this.events.emit('wallet.withdrawal.completed', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                amount: tx.amount,
+                currency: tx.currency,
+                transactionId: tx.id,
+            });
+            return;
+        }
+        if (status === 'failed') {
+            await this.finalizeFailedWithdrawal({ tx, adminId: null, userId, amount: tx.amount });
+        }
+    }
     // Evaluates the auto-approval gates and settles the payout if all pass; returns undefined to
     // leave the row pending for the manual queue. NEVER throws: any error fails closed to manual.
     async maybeAutoApprove(args) {
-        // Cheap gates first (auto-approval off, or crypto - never auto-approved): skip opening a tx/lock.
-        if (!this.platformConfig?.autoWithdrawal?.enabled || args.rail !== 'fiat')
+        if (!this.platformConfig?.autoWithdrawal?.enabled) {
             return undefined;
+        }
         try {
             const cfg = this.platformConfig.autoWithdrawal;
             // Threshold/KYC/risk/velocity gates run outside any lock; only the cap check below needs serializing.
             const gates = await this.evaluateAutoApproval(args);
-            if (!gates)
+            if (!gates) {
                 return undefined;
+            }
             // Serialize the cap-check-and-flip per user with an advisory lock: without it two concurrent
             // withdrawals read the same daily-cap usage and both auto-approve, bypassing the cap. The cap read
             // and the flip that writes the marker commit together, so a blocked caller re-reads current usage.
             // PSP settlement runs AFTER, outside the lock.
             const decided = await this.drizzle.db.transaction((txn) => withAdvisoryXactLock(txn, args.userId, async () => {
                 const caps = await this.autoApprovalCaps({ walletId: args.walletId, amount: args.amount, cfg }, txn);
-                if (caps.exceeded)
+                if (caps.exceeded) {
                     return null;
+                }
                 const tx = await this.flipToProcessing({
                     txn,
                     withdrawalId: args.transactionId,
@@ -478,8 +1015,9 @@ export class WalletService {
                 });
                 return { tx, caps };
             }));
-            if (!decided)
+            if (!decided) {
                 return undefined;
+            }
             const decision = {
                 ...gates,
                 dailyCapAmount: cfg.dailyCapAmount ?? null,
@@ -494,7 +1032,12 @@ export class WalletService {
                     action: 'wallet.withdrawal.auto_approved',
                     resourceType: 'wallet_transaction',
                     resourceId: args.transactionId,
-                    after: { userId: args.userId, amount: args.amount, currency: args.currency, ...decision },
+                    after: {
+                        userId: args.userId,
+                        amount: args.amount,
+                        currency: args.currency,
+                        ...decision,
+                    },
                 });
             }
             catch (err) {
@@ -518,69 +1061,340 @@ export class WalletService {
     // route to manual. The daily-cap check is NOT here - it runs under the advisory lock (see maybeAutoApprove).
     async evaluateAutoApproval({ userId, amount, walletId, rail, }) {
         const cfg = this.platformConfig?.autoWithdrawal;
-        if (!cfg?.enabled)
-            return null;
-        // Hard stop: crypto is irreversible and AML-sensitive - never auto-approved.
-        if (rail !== 'fiat')
+        if (!cfg?.enabled) {
             return null;
-        const threshold = await this.resolveAutoThreshold(userId);
-        if (!threshold || threshold.value <= 0)
+        }
+        const threshold = await this.resolveAutoThreshold(userId, rail);
+        if (!threshold || moneyToNumber(threshold.value) <= 0) {
             return null;
-        if (amount > threshold.value)
+        }
+        if (moneyToNumber(amount) > moneyToNumber(threshold.value)) {
             return null;
+        }
         // Independent of kyc.gateWithdrawals: auto-approval always demands a passing status; anything else fails closed.
         const kycStatus = await this.autoApprovalKycStatus(userId);
-        if (!kycStatus || !KYC_PASS_STATUSES.has(kycStatus))
+        if (!kycStatus || !KYC_PASS_STATUSES.has(normalizeKycStatus(kycStatus))) {
             return null;
-        const riskTags = await this.autoApprovalRiskTags(userId, cfg.excludeRiskFlags);
+        }
+        const effectiveExcludeTags = threshold.config.excludeRiskFlags;
+        const riskTags = await this.autoApprovalRiskTags(userId, effectiveExcludeTags);
         // null = exclusions configured but the lookup port is unavailable => fail closed.
-        if (riskTags === null)
+        if (riskTags === null) {
             return null;
-        if (riskTags.some((t) => cfg.excludeRiskFlags.includes(t)))
+        }
+        if (riskTags.some((t) => effectiveExcludeTags.includes(t))) {
             return null;
+        }
         const heuristics = await this.autoApprovalHeuristics({ walletId, amount });
-        if (heuristics.largeAmount || heuristics.highFrequency)
+        if (heuristics.largeAmount || heuristics.highFrequency) {
             return null;
+        }
         return {
             threshold: threshold.value,
             thresholdSource: threshold.source,
             kycStatus,
             riskTagsEvaluated: riskTags,
+            effectiveExcludeTags,
         };
     }
-    // Per-player rule wins over the global fiat threshold; null when neither is set.
-    async resolveAutoThreshold(userId) {
+    async resolveAutoThreshold(userId, rail) {
+        // Always read the global singleton first, even when a per-player override may end up
+        // winning below - an unseeded install (missing row) must fail closed for EVERY player,
+        // not just those without an override. getAutoWithdrawalConfig() throws when absent.
+        const config = await this.getAutoWithdrawalConfig();
         const [rule] = await this.drizzle.db
             .select()
             .from(autoWithdrawalRule)
             .where(eq(autoWithdrawalRule.userId, userId));
-        if (rule)
-            return { value: Number(rule.threshold), source: 'per-player' };
-        const global = this.platformConfig?.autoWithdrawal?.fiatThreshold;
-        if (global !== undefined)
-            return { value: global, source: 'global' };
-        return null;
+        if (rule) {
+            return { value: rule.threshold, source: 'per-player', config };
+        }
+        const global = rail === 'crypto' ? config.cryptoThreshold : config.fiatThreshold;
+        return { value: global, source: 'global', config };
+    }
+    // The row always exists in a properly-seeded install (seeded once) - a
+    // missing row is an unexpected failure mode on the READ path, not a normal
+    // "unconfigured" state, so this throws rather than silently defaulting.
+    // maybeAutoApprove's outer try/catch handles that thrown error the same as any
+    // other unexpected error: fail closed to pending.
+    async getAutoWithdrawalConfig() {
+        const config = await this.getAutoWithdrawalConfigOrNull();
+        if (!config) {
+            throw new AutoWithdrawalConfigNotFoundError('global');
+        }
+        return config;
+    }
+    // Non-throwing variant for callers that need to tell "missing" from "found"
+    // without a try/catch (eg the router's audit `before` read).
+    async getAutoWithdrawalConfigOrNull() {
+        const [row] = await this.drizzle.db
+            .select()
+            .from(walletAutoWithdrawalConfig)
+            .where(eq(walletAutoWithdrawalConfig.singletonKey, 'global'));
+        return row ? toAutoWithdrawalConfigDto(row) : null;
+    }
+    // Upsert, not a plain UPDATE: the WRITE path lets a Super Admin self-heal a
+    // missing singleton row (eg an install that skipped the seed step) through the
+    // existing route with zero new surface. The READ path (getAutoWithdrawalConfig,
+    // resolveAutoThreshold) still throws on a missing row and stays fail-closed -
+    // a withdrawal must never silently create config.
+    //
+    // Update + audit write run in one transaction: an audit-write failure must roll back
+    // the threshold change too, or the config could change with no audit trail.
+    async setAutoWithdrawalConfig(adminId, { fiatThreshold, cryptoThreshold, excludeRiskFlags, }, meta) {
+        return this.drizzle.db.transaction(async (txn) => {
+            const [before] = await txn
+                .select()
+                .from(walletAutoWithdrawalConfig)
+                .where(eq(walletAutoWithdrawalConfig.singletonKey, 'global'));
+            const rows = await txn
+                .insert(walletAutoWithdrawalConfig)
+                .values({
+                singletonKey: 'global',
+                fiatThreshold,
+                cryptoThreshold,
+                excludeRiskFlags,
+                updatedBy: adminId,
+            })
+                .onConflictDoUpdate({
+                target: walletAutoWithdrawalConfig.singletonKey,
+                set: { fiatThreshold, cryptoThreshold, excludeRiskFlags, updatedBy: adminId },
+            })
+                .returning();
+            const config = toAutoWithdrawalConfigDto(findOneOrThrow(rows, new AutoWithdrawalConfigNotFoundError('global')));
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.auto_withdrawal_config.set',
+                resourceType: 'auto_withdrawal_config',
+                resourceId: config.id,
+                before: before
+                    ? {
+                        fiatThreshold: before.fiatThreshold,
+                        cryptoThreshold: before.cryptoThreshold,
+                        excludeRiskFlags: before.excludeRiskFlags,
+                    }
+                    : null,
+                after: {
+                    fiatThreshold: config.fiatThreshold,
+                    cryptoThreshold: config.cryptoThreshold,
+                    excludeRiskFlags: config.excludeRiskFlags,
+                },
+                ...meta,
+            });
+            return config;
+        });
+    }
+    async getBonusRolloverStatus(userId, status = 'active') {
+        const rows = await this.drizzle.db
+            .select()
+            .from(walletBonusCredit)
+            .where(and(eq(walletBonusCredit.userId, userId), eq(walletBonusCredit.status, status)))
+            .orderBy(desc(walletBonusCredit.createdAt))
+            .limit(50);
+        return { credits: rows.map(toBonusCreditDto) };
+    }
+    async getBonusRolloverConfig() {
+        const config = await this.getBonusRolloverConfigOrNull();
+        if (!config) {
+            throw new BonusRolloverConfigNotFoundError('global');
+        }
+        return config;
+    }
+    async getBonusRolloverConfigOrNull() {
+        const [row] = await this.drizzle.db
+            .select()
+            .from(walletBonusRolloverConfig)
+            .where(eq(walletBonusRolloverConfig.singletonKey, 'global'));
+        return row ? toBonusRolloverConfigDto(row) : null;
+    }
+    async setBonusRolloverConfig(adminId, { multiplier }, meta) {
+        return this.drizzle.db.transaction(async (txn) => {
+            const [before] = await txn
+                .select()
+                .from(walletBonusRolloverConfig)
+                .where(eq(walletBonusRolloverConfig.singletonKey, 'global'));
+            const rows = await txn
+                .insert(walletBonusRolloverConfig)
+                .values({ singletonKey: 'global', multiplier, updatedBy: adminId })
+                .onConflictDoUpdate({
+                target: walletBonusRolloverConfig.singletonKey,
+                set: { multiplier, updatedBy: adminId, updatedAt: new Date() },
+            })
+                .returning();
+            const config = toBonusRolloverConfigDto(findOneOrThrow(rows, new BonusRolloverConfigNotFoundError('global')));
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.bonus_rollover_config.set',
+                resourceType: 'bonus_rollover_config',
+                resourceId: config.id,
+                before: before ? { multiplier: before.multiplier } : null,
+                after: { multiplier: config.multiplier },
+                ...meta,
+            });
+            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)
+        if (!this.directory) {
             return null;
+        }
         const [summary] = await this.directory.lookupPlayers([userId]);
         return summary?.kycStatus ?? null;
     }
     // Active tag keys; [] when no exclusions configured or none carried; null when configured but the port is unbound (fail closed).
     async autoApprovalRiskTags(userId, excludeRiskFlags) {
-        if (excludeRiskFlags.length === 0)
+        if (excludeRiskFlags.length === 0) {
             return [];
-        if (!this.riskTags)
+        }
+        if (!this.riskTags) {
             return null;
+        }
         const byUser = await this.riskTags.getActiveTagKeys([userId]);
         return byUser.get(userId) ?? [];
     }
     async autoApprovalHeuristics({ walletId, amount, }) {
         const frequent = await this.frequentWithdrawalWalletIds(this.drizzle.db, [walletId]);
         return {
-            largeAmount: amount >= LARGE_WITHDRAWAL_THRESHOLD,
+            largeAmount: moneyToNumber(amount) >= moneyToNumber(LARGE_WITHDRAWAL_THRESHOLD),
             highFrequency: frequent.has(walletId),
         };
     }
@@ -588,8 +1402,9 @@ export class WalletService {
     // Single source of the velocity check, shared by the review queue tag and the auto-approval heuristic.
     async frequentWithdrawalWalletIds(db, walletIds) {
         const frequent = new Set();
-        if (walletIds.length === 0)
+        if (walletIds.length === 0) {
             return frequent;
+        }
         const since = new Date(Date.now() - HIGH_FREQUENCY_WINDOW_MS);
         const counts = await db
             .select({ walletId: walletTransaction.walletId, n: count() })
@@ -597,8 +1412,9 @@ export class WalletService {
             .where(and(eq(walletTransaction.type, 'withdrawal'), gte(walletTransaction.createdAt, since), inArray(walletTransaction.walletId, walletIds)))
             .groupBy(walletTransaction.walletId);
         for (const row of counts) {
-            if (Number(row.n) >= HIGH_FREQUENCY_MIN_COUNT)
+            if (Number(row.n) >= HIGH_FREQUENCY_MIN_COUNT) {
                 frequent.add(row.walletId);
+            }
         }
         return frequent;
     }
@@ -607,24 +1423,30 @@ export class WalletService {
     async autoApprovalCaps({ walletId, amount, cfg, }, db) {
         const since = new Date(Date.now() - DAILY_CAP_WINDOW_MS);
         const [row] = await db
-            .select({ total: sql `coalesce(sum(${walletTransaction.amount}), 0)`, n: count() })
+            .select({
+            total: sql `coalesce(sum(${walletTransaction.amount}), 0)`,
+            n: count(),
+        })
             .from(walletTransaction)
             .where(and(eq(walletTransaction.walletId, walletId), eq(walletTransaction.type, 'withdrawal'), eq(walletTransaction.reviewReason, AUTO_APPROVED_REASON), gte(walletTransaction.createdAt, since)));
-        const amountUsed = Number(row?.total ?? 0);
+        const amountUsed = row?.total ?? '0';
         const countUsed = Number(row?.n ?? 0);
-        const amountExceeded = cfg.dailyCapAmount !== undefined && amountUsed + amount > cfg.dailyCapAmount;
+        // Cap comparison is a review-queue decision, not a ledger write - moneyToNumber is the
+        // documented single conversion point (see the helper's own doc comment).
+        const amountExceeded = cfg.dailyCapAmount !== undefined &&
+            moneyToNumber(amountUsed) + moneyToNumber(amount) > moneyToNumber(cfg.dailyCapAmount);
         const countExceeded = cfg.dailyCapCount !== undefined && countUsed + 1 > cfg.dailyCapCount;
         return { exceeded: amountExceeded || countExceeded, amountUsed, countUsed };
     }
     async setAutoWithdrawalRule({ userId, threshold, reason, createdBy, }) {
-        const [row] = await this.drizzle.db
+        const row = findOneOrThrow(await this.drizzle.db
             .insert(autoWithdrawalRule)
-            .values({ userId, threshold: threshold.toString(), reason, createdBy })
+            .values({ userId, threshold, reason, createdBy })
             .onConflictDoUpdate({
             target: autoWithdrawalRule.userId,
-            set: { threshold: threshold.toString(), reason, createdBy },
+            set: { threshold, reason, createdBy },
         })
-            .returning();
+            .returning(), new WalletNotFoundError(userId));
         return toAutoWithdrawalRuleDto(row);
     }
     async getAutoWithdrawalRule(userId) {
@@ -641,7 +1463,7 @@ export class WalletService {
             .returning({ id: autoWithdrawalRule.id });
         return deleted.length > 0;
     }
-    async rejectWithdrawal(adminId, withdrawalId, reason) {
+    async rejectWithdrawal(adminId, withdrawalId, reason, meta) {
         const reviewedAt = new Date();
         const tx = await this.drizzle.db.transaction(async (txn) => {
             const current = findOneOrThrow(await txn
@@ -652,40 +1474,51 @@ export class WalletService {
             if (current.status !== 'pending' || current.type !== 'withdrawal') {
                 throw new WithdrawalNotPendingError();
             }
-            const [updated] = await txn
+            const updated = findOneOrThrow(await txn
                 .update(walletTransaction)
                 .set({ status: 'rejected', reviewedBy: adminId, reviewedAt, reviewReason: reason })
                 .where(eq(walletTransaction.id, withdrawalId))
-                .returning();
-            await txn
-                .update(wallet)
-                .set({ balance: sql `${wallet.balance} + ${updated.amount}` })
-                .where(eq(wallet.id, updated.walletId));
+                .returning(), new WithdrawalNotFoundError(withdrawalId));
+            await creditWalletBalance(txn, updated.walletId, updated.currency, updated.amount);
             return updated;
         });
         const userId = await this.userIdForWallet(tx.walletId);
         this.events.emit('wallet.withdrawal.rejected', {
             userId,
-            amount: Number(tx.amount),
+            amount: tx.amount,
             currency: tx.currency,
             transactionId: tx.id,
             adminId,
             reason,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
         });
         return { transactionId: tx.id, status: 'rejected' };
     }
-    async getTransactions(userId, page, limit) {
+    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)
+        if (!walletRecord) {
             return { items: [], total: 0, page, limit };
+        }
+        const dir = (sortOrder ?? 'desc') === 'asc' ? asc : desc;
+        const TX_SORT_COLS = {
+            createdAt: walletTransaction.createdAt,
+            amount: walletTransaction.amount,
+            type: walletTransaction.type,
+            status: walletTransaction.status,
+            currency: walletTransaction.currency,
+            rail: walletTransaction.rail,
+            reviewedAt: walletTransaction.reviewedAt,
+        };
+        const col = TX_SORT_COLS[sortBy ?? 'createdAt'];
         const where = eq(walletTransaction.walletId, walletRecord.id);
         const [txs, [{ n }]] = await Promise.all([
             db
                 .select()
                 .from(walletTransaction)
                 .where(where)
-                .orderBy(desc(walletTransaction.createdAt))
+                .orderBy(dir(col), desc(walletTransaction.id))
                 .limit(limit)
                 .offset(pageToOffset(page, limit)),
             db.select({ n: count() }).from(walletTransaction).where(where),
@@ -694,16 +1527,155 @@ export class WalletService {
             items: txs.map((tx) => ({
                 id: tx.id,
                 type: tx.type,
-                amount: Number(tx.amount),
+                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,
             limit,
         };
     }
+    async getOrCreateDepositAddress(userId, currency, network) {
+        const existing = await this.findDepositAddress(userId, currency, network);
+        if (existing) {
+            return toDepositAddressResult(existing);
+        }
+        if (!this.payment.issueDepositAddress) {
+            throw new DepositAddressUnsupportedError();
+        }
+        const issued = await this.payment.issueDepositAddress(userId, currency, network);
+        const [row] = await this.drizzle.db
+            .insert(walletDepositAddress)
+            .values({
+            userId,
+            currency,
+            network: network ?? null,
+            address: issued.address,
+            tag: issued.tag ?? null,
+            providerName: await this.providerNameFor(currency, network ?? null),
+        })
+            .onConflictDoNothing()
+            .returning();
+        if (row) {
+            return toDepositAddressResult(row);
+        }
+        const winner = await this.findDepositAddress(userId, currency, network);
+        if (!winner) {
+            throw new Error(`wallet deposit address: idempotency conflict but no row found (userId=${userId}, currency=${currency}, network=${network ?? 'none'})`);
+        }
+        return toDepositAddressResult(winner);
+    }
+    /**
+     * `providerName` is the vendor the webhook route already resolved (verifier + adapter
+     * came from the same registry entry) - it is only used to label a finding when this
+     * deposit can't be attributed, never to look anything up. Defaults to the single
+     * default binding for callers (tests, a poller with no named provider) that don't care.
+     */
+    async creditDepositByAddress(event, providerName = DEFAULT_PAYMENT_PROVIDER) {
+        const depositAddress = await this.findDepositAddressByAddress(event);
+        if (!depositAddress) {
+            // A known vendor defect hits this live: a token deposit reported under a sibling
+            // token's asset id never resolves to a row. Never let it survive only as a log
+            // line - file a finding so an operator can attribute and manually credit it.
+            logger.warn({ address: event.address, network: event.network, tag: event.tag }, 'payment webhook: no wallet_deposit_address for inbound deposit');
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId: LIVE_WEBHOOK_RUN_ID,
+                providerName,
+                kind: 'unattributed_deposit',
+                currency: event.currency,
+                network: event.network ?? null,
+                amount: event.amount,
+                address: event.address,
+                tag: event.tag ?? null,
+                txHash: event.txHash,
+                externalId: event.externalId,
+                detail: 'no wallet_deposit_address matched this address/network/tag',
+            });
+            return;
+        }
+        if (event.network === undefined &&
+            event.currency.toUpperCase() !== depositAddress.currency.toUpperCase()) {
+            // Same "do not silently drop" discipline as the no-address branch above - this is
+            // the push-path counterpart to the poll-path's currency_mismatch finding.
+            logger.warn({
+                address: event.address,
+                eventCurrency: event.currency,
+                addressCurrency: depositAddress.currency,
+            }, 'payment webhook: currency mismatch for inbound deposit');
+            await recordReconciliationFinding(this.drizzle.db, {
+                runId: LIVE_WEBHOOK_RUN_ID,
+                providerName: depositAddress.providerName,
+                kind: 'currency_mismatch',
+                currency: event.currency,
+                network: event.network ?? depositAddress.network,
+                amount: event.amount,
+                address: event.address,
+                tag: event.tag ?? null,
+                txHash: event.txHash,
+                externalId: event.externalId,
+                detail: `currency mismatch: event reported ${event.currency}, address issued for ${depositAddress.currency}`,
+            });
+            return;
+        }
+        const { transactionId, replayed } = await this.drizzle.db.transaction(async (txn) => {
+            let [walletRecord] = await txn
+                .select()
+                .from(wallet)
+                .where(eq(wallet.userId, depositAddress.userId));
+            if (!walletRecord) {
+                walletRecord = findOneOrThrow(await txn
+                    .insert(wallet)
+                    .values({ userId: depositAddress.userId, currency: event.currency })
+                    .returning(), new WalletNotFoundError(depositAddress.userId));
+            }
+            const [inserted] = await txn
+                .insert(walletTransaction)
+                .values({
+                walletId: walletRecord.id,
+                type: 'deposit',
+                amount: event.amount,
+                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,
+                txHash: event.txHash,
+            })
+                .onConflictDoNothing()
+                .returning();
+            if (inserted) {
+                await creditWalletBalance(txn, walletRecord.id, event.currency, event.amount);
+                return { transactionId: inserted.id, replayed: false };
+            }
+            const [winner] = await txn
+                .select()
+                .from(walletTransaction)
+                .where(eq(walletTransaction.providerRefId, event.externalId));
+            if (!winner) {
+                throw new Error(`payment webhook: idempotency conflict but no row found (externalId=${event.externalId})`);
+            }
+            return { transactionId: winner.id, replayed: true };
+        });
+        if (!replayed) {
+            this.events.emit('wallet.deposit.completed', {
+                userId: depositAddress.userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(depositAddress.userId),
+                amount: event.amount,
+                currency: event.currency,
+                transactionId,
+            });
+        }
+    }
     async userIdForWallet(walletId) {
         const record = findOneOrThrow(await this.drizzle.db
             .select({ userId: wallet.userId })
@@ -718,5 +1690,179 @@ export class WalletService {
             .where(and(eq(walletTransaction.walletId, walletId), eq(walletTransaction.idempotencyKey, idempotencyKey)));
         return existing;
     }
+    async findDepositAddress(userId, currency, network) {
+        const [row] = await this.drizzle.db
+            .select()
+            .from(walletDepositAddress)
+            .where(and(eq(walletDepositAddress.userId, userId), eq(walletDepositAddress.currency, currency), network === undefined
+            ? isNull(walletDepositAddress.network)
+            : eq(walletDepositAddress.network, network)));
+        return row;
+    }
+    async findDepositAddressByAddress({ address, network, tag, }) {
+        const rows = await this.drizzle.db
+            .select()
+            .from(walletDepositAddress)
+            .where(and(eq(walletDepositAddress.address, address), tag === undefined ? isNull(walletDepositAddress.tag) : eq(walletDepositAddress.tag, tag), network === undefined
+            ? undefined
+            : or(eq(walletDepositAddress.network, network), isNull(walletDepositAddress.network))));
+        const owners = new Set(rows.map((row) => row.userId));
+        if (owners.size > 1) {
+            throw new AmbiguousDepositAddressError(address, network);
+        }
+        return rows.find((row) => row.network === network) ?? rows[0];
+    }
+    /**
+     * The player's own payout address book. Every method here is scoped on `userId` - a
+     * saved address is personal data with no admin read path, so there is
+     * deliberately no variant of these that takes an arbitrary user id.
+     */
+    async listWithdrawalAddresses(userId, currency) {
+        const rows = await this.drizzle.db
+            .select()
+            .from(walletWithdrawalAddress)
+            .where(and(eq(walletWithdrawalAddress.userId, userId), currency === undefined ? undefined : eq(walletWithdrawalAddress.currency, currency)))
+            .orderBy(desc(walletWithdrawalAddress.createdAt));
+        return rows.map(toWithdrawalAddressDto);
+    }
+    async createWithdrawalAddress(userId, input, meta) {
+        // Shares the wallet mutation budget with deposit/withdraw: the row cap alone does
+        // not bound writes, since deleting frees a slot and lets a client churn forever.
+        await this.rateLimit(userId);
+        // ponytail: count-then-insert, so N concurrent creates can land N over the cap.
+        // Move to an insert...where (select count) < limit if that ever matters.
+        const [existing] = await this.drizzle.db
+            .select({ total: count() })
+            .from(walletWithdrawalAddress)
+            .where(eq(walletWithdrawalAddress.userId, userId));
+        if ((existing?.total ?? 0) >= WITHDRAWAL_ADDRESS_LIMIT) {
+            throw new WithdrawalAddressLimitReachedError(WITHDRAWAL_ADDRESS_LIMIT);
+        }
+        // Registered with the custody provider BEFORE the row exists, so a rejected or unreachable
+        // provider leaves no saved address the player would believe they can withdraw to. The port
+        // is required to be idempotent, so the conflict path below cannot orphan a destination.
+        const whitelisted = await this.whitelistWithdrawalAddress(userId, input);
+        // onConflictDoNothing turns the unique index into a domain conflict rather than a
+        // 500 - a double-submitted form is a 409, not an incident.
+        const [row] = await this.drizzle.db
+            .insert(walletWithdrawalAddress)
+            .values({ userId, ...input, ...whitelisted })
+            .onConflictDoNothing()
+            .returning();
+        if (!row) {
+            throw new WithdrawalAddressAlreadyExistsError();
+        }
+        await this.audit.record({
+            actorId: userId,
+            actorType: 'player',
+            action: 'wallet.withdrawal_address.created',
+            resourceType: 'wallet_withdrawal_address',
+            resourceId: row.id,
+            // The address string is deliberately absent: the audit log is admin-readable and
+            // a player's saved addresses are not. The row id is enough to correlate.
+            after: { label: row.label, currency: row.currency, network: row.network },
+            ...meta,
+        });
+        return toWithdrawalAddressDto(row);
+    }
+    /**
+     * Refuses a payout to an address the provider has not approved. A no-op for an adapter that
+     * does not whitelist, and for a fiat rail, which has no address at all.
+     */
+    async requireWhitelistedWalletId(userId, currency, network, destinationAddress) {
+        if (!this.payment.whitelistWithdrawalAddress || !destinationAddress) {
+            return null;
+        }
+        const walletId = await this.whitelistedWalletId(userId, currency, network, destinationAddress);
+        if (!walletId) {
+            throw new DestinationAddressNotWhitelistedError();
+        }
+        return walletId;
+    }
+    /**
+     * The approved destination saved for this address, or null. Matched on the address itself
+     * rather than an id on the transaction, because a withdrawal is requested by address and may
+     * name one the player never saved.
+     */
+    async whitelistedWalletId(userId, currency, network, address) {
+        if (!this.payment.whitelistWithdrawalAddress || !address) {
+            return null;
+        }
+        const providerName = await this.providerNameFor(currency, network);
+        const [row] = await this.drizzle.db
+            .select({
+            id: walletWithdrawalAddress.id,
+            network: walletWithdrawalAddress.network,
+            providerName: walletWithdrawalAddress.providerName,
+            providerWalletId: walletWithdrawalAddress.providerWalletId,
+        })
+            .from(walletWithdrawalAddress)
+            .where(and(eq(walletWithdrawalAddress.userId, userId), eq(walletWithdrawalAddress.currency, currency), eq(walletWithdrawalAddress.address, address), ...(network ? [eq(walletWithdrawalAddress.network, network)] : [])))
+            .limit(1);
+        if (!row) {
+            return null;
+        }
+        // An id minted by a different provider names nothing in the current one, and a row
+        // saved while no whitelisting adapter was bound has no id at all. Both re-register
+        // with the provider that will actually settle, rather than failing a payout on a
+        // saved address the player cannot fix themselves.
+        if (row.providerWalletId && row.providerName === providerName) {
+            return row.providerWalletId;
+        }
+        const { providerWalletId } = await this.payment.whitelistWithdrawalAddress({
+            userId,
+            currency,
+            network: row.network,
+            address,
+        });
+        await this.drizzle.db
+            .update(walletWithdrawalAddress)
+            .set({ providerName, providerWalletId })
+            .where(eq(walletWithdrawalAddress.id, row.id));
+        return providerWalletId;
+    }
+    /**
+     * Delegates to the bound payment adapter when it whitelists destinations, and returns nothing
+     * to store when it does not. A vendor failure propagates rather than being swallowed: saving
+     * the address anyway would produce a row that looks usable and fails only once the player has
+     * committed to a payout.
+     */
+    async whitelistWithdrawalAddress(userId, input) {
+        if (!this.payment.whitelistWithdrawalAddress) {
+            return {};
+        }
+        const { providerWalletId } = await this.payment.whitelistWithdrawalAddress({
+            userId,
+            currency: input.currency,
+            network: input.network,
+            address: input.address,
+        });
+        return {
+            providerName: await this.providerNameFor(input.currency, input.network),
+            providerWalletId,
+        };
+    }
+    /** False when the row does not exist OR belongs to someone else - the caller cannot
+     * tell the two apart, which is what stops the id space being probed. */
+    async deleteWithdrawalAddress(userId, id, meta) {
+        await this.rateLimit(userId);
+        const [row] = await this.drizzle.db
+            .delete(walletWithdrawalAddress)
+            .where(and(eq(walletWithdrawalAddress.id, id), eq(walletWithdrawalAddress.userId, userId)))
+            .returning();
+        if (!row) {
+            return false;
+        }
+        await this.audit.record({
+            actorId: userId,
+            actorType: 'player',
+            action: 'wallet.withdrawal_address.deleted',
+            resourceType: 'wallet_withdrawal_address',
+            resourceId: row.id,
+            before: { label: row.label, currency: row.currency, network: row.network },
+            ...meta,
+        });
+        return true;
+    }
 }
 //# sourceMappingURL=wallet.service.js.map