@openora/core 0.4.1-canary.12 → 0.4.1-canary.121

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

@@ -1,32 +1,231 @@
-import { makeNotFoundError, makeConflictError, createDomainError, findOneOrThrow, pageToOffset, withAdvisoryXactLock, assertRateLimit, createLogger, moneyToNumber, } 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, RgLimitExceededError, DEFAULT_PAYMENT_PROVIDER, railFor as sharedRailFor, } 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', { code: 'WALLET_ASSET_BALANCE_HELD' });
+export const WalletAssetHasIssuedAddressesError = makeConflictError('WalletAssetHasIssuedAddressesError', 'A deposit address was already issued for this currency and network', { code: 'WALLET_ASSET_ADDRESS_ISSUED' });
+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', { code: 'WALLET_ASSET_TRANSACTION_IN_FLIGHT' });
+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`);
+export const DepositDisabledError = createDomainError('DepositDisabledError', (currency, network) => network
+    ? `Deposits are disabled for ${currency} on ${network}`
+    : `Deposits are disabled for ${currency} on every configured network`);
+export const BelowMinimumDepositError = createDomainError('BelowMinimumDepositError', (amount, minimum, currency, network) => `Deposit 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`);
+// 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,
+        destinationTag: row.destinationTag,
+        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 assertDepositAllowed(assets, currency, network) {
+    if (assets.length === 0) {
+        // No catalog row at all means the operator never configured this currency (a fiat
+        // PSP), and a currency-level request passes through unchecked. A request naming a
+        // network does not: the pair it names does not exist - either a typo or a catalog
+        // row deleted while this request was in flight - so it fails closed.
+        if (network !== undefined) {
+            throw new UnsupportedNetworkError(currency, network.toUpperCase());
+        }
+        return;
+    }
+    if (network === undefined) {
+        if (!assets.some((asset) => asset.depositEnabled)) {
+            throw new DepositDisabledError(currency, null);
+        }
+        return;
+    }
+    const wanted = network.toUpperCase();
+    const asset = assets.find((candidate) => candidate.network.toUpperCase() === wanted);
+    if (!asset) {
+        throw new UnsupportedNetworkError(currency, wanted);
+    }
+    if (!asset.depositEnabled) {
+        throw new DepositDisabledError(currency, asset.network);
+    }
+}
+export function assertAboveMinimumDeposit(assets, amount, currency, network) {
+    const enabled = assets.filter((asset) => asset.depositEnabled);
+    const wanted = network?.toUpperCase();
+    const applicable = wanted
+        ? enabled.filter((asset) => asset.network.toUpperCase() === wanted)
+        : enabled;
+    const floor = applicable.reduce((lowest, asset) => !lowest || moneyCompare(asset.minDeposit, lowest.minDeposit) < 0 ? asset : lowest, undefined);
+    if (floor && moneyCompare(amount, floor.minDeposit) < 0) {
+        throw new BelowMinimumDepositError(amount, floor.minDeposit, currency, floor.network);
+    }
+}
+export const railFor = sharedRailFor;
+// 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 async function readWalletBalances(txn, userId) {
+    const [record] = await txn.select().from(wallet).where(eq(wallet.userId, userId));
+    if (!record) {
+        return { activeCurrency: DEFAULT_WALLET_CURRENCY, balances: [] };
+    }
+    const balances = await txn
+        .select({ currency: walletBalance.currency, balance: walletBalance.amount })
+        .from(walletBalance)
+        .where(eq(walletBalance.walletId, record.id))
+        .orderBy(walletBalance.currency);
+    return { activeCurrency: record.currency, balances };
+}
+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';
+/** Serialises one player's PSP deposits, so an RG reservation cannot be spent twice. */
+const depositSlotKey = (userId) => `wallet-deposit:${userId}`;
+const MANUAL_ADJUSTMENT_TYPES = new Set(['manual_credit', 'manual_debit']);
 function namespacedIdempotencyKey(namespace, rawKey) {
     const hex = createHash('sha256').update(`${namespace}:${rawKey}`).digest('hex');
     return [
@@ -47,6 +246,14 @@ 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,
@@ -58,10 +265,49 @@ function toAutoWithdrawalRuleDto(row) {
         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
@@ -75,46 +321,151 @@ export class WalletService {
     drizzle;
     events;
     payment;
+    paymentProviders;
+    identityReader;
     directory;
     platformConfig;
     limiter;
     riskTags;
+    tagEvaluationCommands;
     audit;
-    constructor({ drizzle, events, payment, directory, platformConfig, limiter, riskTags, audit, }) {
+    rgLimits;
+    constructor({ drizzle, events, payment, paymentProviders, directory, identityReader, platformConfig, limiter, riskTags, tagEvaluationCommands, audit, rgLimits, }) {
         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;
+        this.rgLimits = rgLimits;
+    }
+    // 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()));
+    }
+    // `for('share')` blocks a concurrent deleteWalletAsset (which takes `for('update')` on
+    // the same rows) from removing the pair while a deposit is being gated against it.
+    depositAssetsForCurrency(currency, db = this.drizzle.db) {
+        return db
+            .select({
+            network: walletAsset.network,
+            minDeposit: walletAsset.minDeposit,
+            depositEnabled: walletAsset.depositEnabled,
+        })
+            .from(walletAsset)
+            .where(eq(walletAsset.currency, currency.toUpperCase()))
+            .for('share');
+    }
+    /**
+     * `network` is optional because not every deposit path knows one: `deposit()` takes a
+     * PSP amount and currency only, so it is gated currency-wide (any enabled network
+     * clears it). Per-network gating applies where a network is actually chosen, ie
+     * `getOrCreateDepositAddress`, which is the path that hands a player a chain address.
+     */
+    async assertDepositable(currency, amount, network, db = this.drizzle.db) {
+        const assets = await this.depositAssetsForCurrency(currency, db);
+        assertDepositAllowed(assets, currency, network);
+        if (amount !== undefined) {
+            assertAboveMinimumDeposit(assets, amount, currency, network);
+        }
+    }
+    async assertWithinRgDepositLimit(tx, userId, amount, currency) {
+        if (!this.rgLimits) {
+            return;
+        }
+        const decision = await this.rgLimits.checkDeposit(tx, userId, amount, currency);
+        if (!decision.allowed) {
+            throw new RgLimitExceededError('deposit_limit_exceeded', decision);
+        }
+    }
+    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;
+    }
+    // Fails closed on a named provider that is no longer registered (removed or
+    // misconfigured after the catalog row was written). Falling back to the default
+    // adapter would pay a withdrawal out through the wrong vendor while still recording
+    // the old provider name - money moved somewhere the ledger does not describe.
+    async paymentAdapterFor(currency, network) {
+        const providerName = await this.providerNameFor(currency, network);
+        if (providerName === DEFAULT_PAYMENT_PROVIDER) {
+            return { providerName, adapter: this.payment };
+        }
+        const adapter = this.paymentProviders.get(providerName)?.adapter;
+        if (!adapter) {
+            throw new WalletAssetUnknownProviderError();
+        }
+        return { providerName, adapter };
     }
     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) {
             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: record.balance,
+            balance: await readWalletBalance(this.drizzle.db, record.id, record.currency),
             currency: record.currency,
         };
     }
+    async getBalances(userId) {
+        return readWalletBalances(this.drizzle.db, userId);
+    }
+    // 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
@@ -124,9 +475,16 @@ export class WalletService {
      * 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.
+     *
+     * Deposit gating is network-aware when a network is known (e.g. via
+     * `getOrCreateDepositAddress`), but here we gate on "any network for this
+     * currency is enabled" because `provider` routing may resolve a specific
+     * network inside `processDeposit`. A fiat PSP (no networks) passes through
+     * unchecked; an explicit network route checks that specific network only.
      */
     async deposit({ userId, amount, currency, provider, idempotencyKey, }) {
         await this.rateLimit(userId);
+        await this.assertDepositable(currency, amount);
         // Short-circuit a replay BEFORE the PSP call - the common retry case (client
         // resends after a timeout) must not re-charge. A genuine concurrent race (two
         // first-attempts for the same key landing here at once) can still both reach the
@@ -139,52 +497,222 @@ export class WalletService {
             }
             preResolvedWallet = found.walletRecord;
         }
-        const psp = await this.payment.processDeposit(amount, currency, { userId, provider });
-        const { transactionId, replayed } = await this.drizzle.db.transaction(async (txn) => {
+        else {
+            [preResolvedWallet] = await this.drizzle.db
+                .select()
+                .from(wallet)
+                .where(eq(wallet.userId, userId));
+        }
+        // Reserve the RG headroom BEFORE charging the PSP: the check and the pending row that
+        // consumes it commit together under the player's deposit lock, so a second concurrent
+        // deposit reads the first one's reservation instead of spending the same headroom.
+        const reservation = await this.drizzle.db.transaction(async (txn) => {
             let walletRecord = preResolvedWallet;
             if (!walletRecord) {
                 [walletRecord] = await txn.select().from(wallet).where(eq(wallet.userId, userId));
             }
             if (!walletRecord) {
-                walletRecord = findOneOrThrow(await txn.insert(wallet).values({ userId, balance: '0', currency }).returning(), new WalletNotFoundError(userId));
+                walletRecord = findOneOrThrow(await txn.insert(wallet).values({ userId, currency }).returning(), new WalletNotFoundError(userId));
+            }
+            const holder = walletRecord;
+            return withAdvisoryXactLock(txn, depositSlotKey(userId), async () => {
+                const namespacedKey = idempotencyKey
+                    ? namespacedIdempotencyKey(DEPOSIT_IDEMPOTENCY_NAMESPACE, idempotencyKey)
+                    : undefined;
+                const existing = namespacedKey
+                    ? await this.findByIdempotencyKey(txn, holder.id, namespacedKey)
+                    : undefined;
+                if (existing) {
+                    this.assertReplayMatches(existing, amount, currency);
+                    return { walletRecord: holder, row: existing, replay: true };
+                }
+                await this.assertWithinRgDepositLimit(txn, userId, amount, currency);
+                const { row } = await this.insertIdempotentTransaction(txn, {
+                    namespace: DEPOSIT_IDEMPOTENCY_NAMESPACE,
+                    walletId: holder.id,
+                    rawIdempotencyKey: idempotencyKey,
+                    amount,
+                    currency,
+                    values: {
+                        walletId: holder.id,
+                        type: 'deposit',
+                        amount,
+                        currency,
+                        status: 'pending',
+                        direction: 'credit',
+                        rail: this.resolveRail(currency),
+                        providerName: provider,
+                    },
+                });
+                return { walletRecord: holder, row, replay: false };
+            });
+        });
+        if (reservation.replay) {
+            return { transactionId: reservation.row.id, status: reservation.row.status };
+        }
+        let psp;
+        try {
+            psp = await this.payment.processDeposit(amount, currency, { userId, provider });
+        }
+        catch (err) {
+            await this.releaseDepositReservation(reservation.row.id);
+            throw err;
+        }
+        // The status guard is the settle-once lock: only the update that moves the row out of
+        // `pending` credits the balance, so a retry that races here reads a replay instead.
+        const { transactionId, replayed } = await this.drizzle.db.transaction(async (txn) => {
+            const [settled] = await txn
+                .update(walletTransaction)
+                .set({ status: 'completed', providerRefId: psp.externalId })
+                .where(and(eq(walletTransaction.id, reservation.row.id), eq(walletTransaction.status, 'pending')))
+                .returning();
+            if (!settled) {
+                return { transactionId: reservation.row.id, replayed: true };
+            }
+            await creditWalletBalance(txn, reservation.walletRecord.id, currency, amount);
+            return { transactionId: settled.id, replayed: false };
+        });
+        if (!replayed) {
+            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: DEPOSIT_IDEMPOTENCY_NAMESPACE,
+                namespace: MANUAL_ADJUSTMENT_IDEMPOTENCY_NAMESPACE,
                 walletId: walletRecord.id,
                 rawIdempotencyKey: idempotencyKey,
                 amount,
                 currency,
                 values: {
                     walletId: walletRecord.id,
-                    type: 'deposit',
+                    type: direction === 'credit' ? 'manual_credit' : 'manual_debit',
                     amount,
                     currency,
                     status: 'completed',
-                    rail: railFor(currency),
-                    providerName: provider,
-                    providerRefId: psp.externalId,
+                    direction,
+                    reviewedBy: adminId,
+                    reviewedAt: new Date(),
+                    reviewReason: reason,
                 },
             });
-            if (!replayed) {
-                await txn
-                    .update(wallet)
-                    .set({ balance: sql `${wallet.balance} + ${amount}::numeric` })
-                    .where(eq(wallet.id, walletRecord.id));
+            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);
             }
-            return { transactionId: row.id, replayed };
+            // 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 };
         });
-        if (!replayed) {
-            this.events.emit('wallet.deposit.completed', {
+        // 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,
+                transactionId: result.transactionId,
+                direction,
+                reason,
+                ip,
+                userAgent,
             });
         }
-        return { transactionId, status: 'completed' };
+        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.
+    /**
+     * Frees a reservation the PSP never charged. Failure to release only leaves the player's
+     * own headroom held until the row is reconciled, so it is logged rather than raised over
+     * the PSP error that caused it.
+     */
+    async releaseDepositReservation(transactionId) {
+        try {
+            await this.drizzle.db
+                .update(walletTransaction)
+                .set({ status: 'failed' })
+                .where(and(eq(walletTransaction.id, transactionId), eq(walletTransaction.status, 'pending')));
+        }
+        catch (err) {
+            logger.error({ err, transactionId }, 'deposit reservation release failed');
+        }
+    }
     async findDepositReplay({ userId, idempotencyKey, amount, currency, }) {
         const [walletRecord] = await this.drizzle.db
             .select()
@@ -200,14 +728,23 @@ export class WalletService {
         this.assertReplayMatches(existing, amount, currency);
         return { walletRecord, replay: { transactionId: existing.id, status: existing.status } };
     }
-    // Replay comparison only (not a ledger write) - moneyToNumber avoids a false mismatch
-    // between an unnormalized caller string (eg "10") and the DB's fixed-scale value ("10.00").
+    // 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 (moneyToNumber(existing.amount) !== moneyToNumber(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.
@@ -246,16 +783,19 @@ export class WalletService {
      * return an already-`completed`/`processing` result if the request
      * qualifies for (and passes) auto-approval - see `maybeAutoApprove`.
      */
-    async withdraw({ userId, amount, currency, idempotencyKey, }) {
+    async withdraw({ userId, amount, currency, network, idempotencyKey, destinationAddress, destinationTag, 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, destinationTag);
         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));
@@ -266,7 +806,7 @@ export class WalletService {
                         status: existing.status,
                         replayed: true,
                         walletId: current.id,
-                        rail: railFor(currency),
+                        rail: this.resolveRail(currency),
                     };
                 }
             }
@@ -282,7 +822,12 @@ export class WalletService {
                     amount,
                     currency,
                     status: 'pending',
-                    rail: railFor(currency),
+                    direction: 'debit',
+                    rail: this.resolveRail(currency),
+                    network: settlementNetwork,
+                    destinationAddress: destinationAddress ?? null,
+                    destinationTag: destinationTag ?? null,
+                    destinationWalletId,
                 },
             });
             if (replayed) {
@@ -291,24 +836,29 @@ 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}::numeric` })
-                .where(and(eq(wallet.id, current.id), gte(wallet.balance, amount)))
-                .returning({ id: wallet.id });
+            const debited = await debitWithdrawableBalance(txn, current.id, currency, amount);
             if (debited.length !== 1) {
-                throw new InsufficientBalanceError(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) {
@@ -316,9 +866,12 @@ export class WalletService {
         }
         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({
@@ -358,17 +911,38 @@ 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 = pageToOffset(page, limit);
         const pageRows = matching.slice(start, start + limit);
@@ -387,14 +961,19 @@ export class WalletService {
             return {
                 transactionId: r.tx.id,
                 userId: r.userId,
+                playerId: summary?.playerId ?? null,
                 username: summary?.username ?? '',
                 amount: r.tx.amount,
                 currency: r.tx.currency,
+                network: r.tx.network,
                 rail: r.tx.rail ?? null,
                 status: r.tx.status,
                 kycStatus: summary?.kycStatus ?? null,
                 riskTags,
                 requestedAt: r.tx.createdAt.toISOString(),
+                destinationAddress: r.tx.destinationAddress,
+                destinationTag: r.tx.destinationTag,
+                txHash: r.tx.txHash,
             };
         });
         return { items, total: matching.length, page, limit };
@@ -404,11 +983,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.
@@ -435,7 +1014,7 @@ export class WalletService {
     }
     // 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 = tx.amount;
         // approved/failed are admin-attributed events (schema requires a uuid adminId); the system auto path
@@ -447,61 +1026,128 @@ export class WalletService {
                 currency: tx.currency,
                 transactionId: tx.id,
                 adminId,
+                ip: meta?.ip ?? null,
+                userAgent: meta?.userAgent ?? null,
             });
         }
+        const { providerName, adapter } = await this.paymentAdapterFor(tx.currency, tx.network);
         let result;
         try {
-            result = await this.payment.processWithdrawal(amount, tx.currency, {
+            result = await adapter.processWithdrawal(amount, tx.currency, {
                 transactionId: tx.id,
                 userId,
                 rail: tx.rail,
                 adminId,
+                destinationAddress: tx.destinationAddress,
+                destinationTag: tx.destinationTag,
+                // 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}::numeric` })
-                    .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,
+                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,
             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 {
@@ -577,11 +1223,7 @@ export class WalletService {
         if (!cfg?.enabled) {
             return null;
         }
-        // Hard stop: crypto is irreversible and AML-sensitive - never auto-approved.
-        if (rail !== 'fiat') {
-            return null;
-        }
-        const threshold = await this.resolveAutoThreshold(userId);
+        const threshold = await this.resolveAutoThreshold(userId, rail);
         if (!threshold || moneyToNumber(threshold.value) <= 0) {
             return null;
         }
@@ -590,15 +1232,16 @@ export class WalletService {
         }
         // 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) {
             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 });
@@ -610,22 +1253,300 @@ export class WalletService {
             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: rule.threshold, source: 'per-player' };
+            return { value: rule.threshold, source: 'per-player', config };
         }
-        const global = this.platformConfig?.autoWithdrawal?.fiatThreshold;
-        if (global !== undefined) {
-            return { value: global, source: 'global' };
+        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 null;
+        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, providerName) {
+        const adapter = (providerName ? this.paymentProviders.get(providerName)?.adapter : undefined) ?? this.payment;
+        if (adapter.supportsAsset && !adapter.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.assertProviderNameValid(input.providerName);
+        this.assertAdapterSupports(input.currency, input.network, 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) {
+        return this.drizzle.db.transaction(async (txn) => {
+            const [before] = await txn
+                .select()
+                .from(walletAsset)
+                .where(and(eq(walletAsset.currency, currency), eq(walletAsset.network, network)))
+                // Held until commit, so an address issuance that already gated against this row
+                // (see depositAssetsForCurrency) commits its address first and is then seen by
+                // the in-use count below, instead of slipping in behind the delete.
+                .for('update');
+            if (!before) {
+                throw new WalletAssetNotFoundError(`${currency}/${network}`);
+            }
+            if (changes.providerAssetId !== undefined) {
+                this.assertAdapterSupports(currency, network, before.providerName ?? undefined);
+            }
+            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)))
+                // Held until commit, so an address issuance that already gated against this row
+                // (see depositAssetsForCurrency) commits its address first and is then seen by
+                // the in-use count below, instead of slipping in behind the delete.
+                .for('update');
+            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({ id: walletBalance.id })
+                .from(walletBalance)
+                .where(and(eq(walletBalance.currency, currency), sql `${walletBalance.amount} > 0`))
+                .for('update');
+            if (held.length > 0) {
+                throw new WalletAssetInUseError();
+            }
+            const [issued] = await txn
+                .select({ n: count() })
+                .from(walletDepositAddress)
+                .where(and(eq(walletDepositAddress.currency, currency), eq(walletDepositAddress.network, network)));
+            if ((issued?.n ?? 0) > 0) {
+                throw new WalletAssetHasIssuedAddressesError();
+            }
+            // 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.
@@ -718,7 +1639,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
@@ -734,10 +1655,7 @@ export class WalletService {
                 .set({ status: 'rejected', reviewedBy: adminId, reviewedAt, reviewReason: reason })
                 .where(eq(walletTransaction.id, withdrawalId))
                 .returning(), new WithdrawalNotFoundError(withdrawalId));
-            await txn
-                .update(wallet)
-                .set({ balance: sql `${wallet.balance} + ${updated.amount}::numeric` })
-                .where(eq(wallet.id, updated.walletId));
+            await creditWalletBalance(txn, updated.walletId, updated.currency, updated.amount);
             return updated;
         });
         const userId = await this.userIdForWallet(tx.walletId);
@@ -748,22 +1666,35 @@ export class WalletService {
             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) {
             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),
@@ -774,14 +1705,163 @@ export class WalletService {
                 type: tx.type,
                 amount: tx.amount,
                 currency: tx.currency,
+                network: tx.network,
                 status: tx.status,
+                direction: tx.direction,
                 createdAt: tx.createdAt.toISOString(),
+                reviewedBy: includeInternal ? tx.reviewedBy : null,
+                reviewedAt: includeInternal ? (tx.reviewedAt?.toISOString() ?? null) : null,
+                reviewReason: includeInternal || MANUAL_ADJUSTMENT_TYPES.has(tx.type) ? tx.reviewReason : null,
             })),
             total: Number(n),
             page,
             limit,
         };
     }
+    async getOrCreateDepositAddress(userId, currency, network) {
+        await this.assertDepositable(currency, undefined, network);
+        const existing = await this.findDepositAddress(userId, currency, network);
+        if (existing) {
+            return toDepositAddressResult(existing);
+        }
+        const { providerName, adapter } = await this.paymentAdapterFor(currency, network ?? null);
+        if (!adapter.issueDepositAddress) {
+            throw new DepositAddressUnsupportedError();
+        }
+        const issued = await adapter.issueDepositAddress(userId, currency, network);
+        // Re-gate inside the transaction that writes the row: the catalog pair can be
+        // disabled or deleted while the vendor call is in flight, and this is what makes
+        // deleteWalletAsset's in-use check race-free.
+        const [row] = await this.drizzle.db.transaction(async (txn) => {
+            await this.assertDepositable(currency, undefined, network, txn);
+            return txn
+                .insert(walletDepositAddress)
+                .values({
+                userId,
+                currency,
+                network: network ?? null,
+                address: issued.address,
+                tag: issued.tag ?? null,
+                providerName,
+            })
+                .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',
+            }, this.audit);
+            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}`,
+            }, this.audit);
+            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',
+                direction: 'credit',
+                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 })
@@ -796,5 +1876,220 @@ 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);
+        // The slot is taken durably BEFORE the vendor call. Whitelisting first let every request
+        // past the cap reach the provider and create a destination there that no local row would
+        // ever describe, because the cap check only ran afterwards. The row is the reservation, and
+        // it is deleted again if the vendor refuses, so a rejected or unreachable provider still
+        // leaves the player no address they would believe they can withdraw to.
+        const reserved = await this.drizzle.db.transaction((txn) => withAdvisoryXactLock(txn, `withdrawal-address-cap:${userId}`, async () => {
+            const [existing] = await txn
+                .select({ total: count() })
+                .from(walletWithdrawalAddress)
+                .where(eq(walletWithdrawalAddress.userId, userId));
+            if ((existing?.total ?? 0) >= WITHDRAWAL_ADDRESS_LIMIT) {
+                throw new WithdrawalAddressLimitReachedError(WITHDRAWAL_ADDRESS_LIMIT);
+            }
+            const [inserted] = await txn
+                .insert(walletWithdrawalAddress)
+                .values({ userId, ...input })
+                .onConflictDoNothing()
+                .returning();
+            if (!inserted) {
+                throw new WithdrawalAddressAlreadyExistsError();
+            }
+            return inserted;
+        }));
+        // The port is required to be idempotent, so releasing and retrying cannot orphan a
+        // destination. A row left behind by a failed release carries no providerWalletId, which
+        // the payout path re-registers rather than trusts - it is never a whitelist bypass.
+        let whitelisted;
+        try {
+            whitelisted = await this.whitelistWithdrawalAddress(userId, input);
+        }
+        catch (err) {
+            await this.releaseWithdrawalAddressSlot(reserved.id);
+            throw err;
+        }
+        const [updated] = Object.keys(whitelisted).length
+            ? await this.drizzle.db
+                .update(walletWithdrawalAddress)
+                .set(whitelisted)
+                .where(eq(walletWithdrawalAddress.id, reserved.id))
+                .returning()
+            : [];
+        const row = updated ?? reserved;
+        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 a destination 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.
+     *
+     * The tag is matched as strictly as the address. On a tag chain one exchange address is shared
+     * by every account behind it, so an address-only check would let a player whitelist their own
+     * account at that exchange and then pay out to a stranger's tag at the same address - an
+     * auto-approved withdrawal would do it with nobody looking.
+     */
+    async requireWhitelistedWalletId(userId, currency, network, destinationAddress, destinationTag) {
+        if (!this.payment.whitelistWithdrawalAddress || !destinationAddress) {
+            return null;
+        }
+        const walletId = await this.whitelistedWalletId(userId, currency, network, destinationAddress, destinationTag);
+        if (!walletId) {
+            throw new DestinationAddressNotWhitelistedError();
+        }
+        return walletId;
+    }
+    /**
+     * The approved destination saved for this (address, tag) pair, or null. Matched on the pair
+     * itself rather than an id on the transaction, because a withdrawal is requested by address
+     * and may name one the player never saved. An absent tag matches only a row saved without
+     * one: a tagged payout against an untagged whitelist row is a different beneficiary.
+     */
+    async whitelistedWalletId(userId, currency, network, address, destinationTag) {
+        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,
+            destinationTag: walletWithdrawalAddress.destinationTag,
+            providerName: walletWithdrawalAddress.providerName,
+            providerWalletId: walletWithdrawalAddress.providerWalletId,
+        })
+            .from(walletWithdrawalAddress)
+            .where(and(eq(walletWithdrawalAddress.userId, userId), eq(walletWithdrawalAddress.currency, currency), eq(walletWithdrawalAddress.address, address), destinationTag
+            ? eq(walletWithdrawalAddress.destinationTag, destinationTag)
+            : isNull(walletWithdrawalAddress.destinationTag), ...(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,
+            ...(row.destinationTag ? { destinationTag: row.destinationTag } : {}),
+        });
+        await this.drizzle.db
+            .update(walletWithdrawalAddress)
+            .set({ providerName, providerWalletId })
+            .where(eq(walletWithdrawalAddress.id, row.id));
+        return providerWalletId;
+    }
+    /** Frees a reserved slot the vendor refused. Idempotent: a row already gone is a no-op. */
+    async releaseWithdrawalAddressSlot(id) {
+        try {
+            await this.drizzle.db
+                .delete(walletWithdrawalAddress)
+                .where(eq(walletWithdrawalAddress.id, id));
+        }
+        catch (err) {
+            logger.error({ err, withdrawalAddressId: id }, 'withdrawal address slot release failed');
+        }
+    }
+    /**
+     * 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,
+            ...(input.destinationTag ? { destinationTag: input.destinationTag } : {}),
+        });
+        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