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

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

@@ -1,26 +1,68 @@
-import { makeNotFoundError, makeConflictError, createDomainError, findOneOrThrow, pageToOffset, withAdvisoryXactLock, assertRateLimit, createLogger, } from '@openora/core/server';
-import { eq, desc, sql, and, gte, lte, count, inArray } from 'drizzle-orm';
+import { makeNotFoundError, makeConflictError, createDomainError, findOneOrThrow, pageToOffset, withAdvisoryXactLock, assertRateLimit, createLogger, moneyToNumber, moneyEquals, } from '@openora/core/server';
+import { normalizeKycStatus, } 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, } from '../schema/index.js';
 const logger = createLogger('wallet');
 export const WalletNotFoundError = makeNotFoundError('Wallet');
 export const WithdrawalNotFoundError = makeNotFoundError('Withdrawal');
+export const AutoWithdrawalConfigNotFoundError = makeNotFoundError('AutoWithdrawalConfig');
 export const 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 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');
+const KYC_PASS_STATUSES = new Set(['approved', 'manually_overridden']);
 export const CurrencyMismatchError = createDomainError('CurrencyMismatchError', (requested, walletCurrency) => `Currency mismatch: requested ${requested}, wallet holds ${walletCurrency}`);
+export const AmbiguousDepositAddressError = createDomainError('AmbiguousDepositAddressError', (address, network) => `Deposit address ${address} on ${network ?? 'an unknown network'} is issued to more than one user`);
 // Crypto currencies settle on the crypto rail (Fireblocks); everything else on the
 // fiat rail (a PSP). The concrete provider is recorded per transaction, not here.
-const CRYPTO_CURRENCIES = new Set(['BTC', 'ETH', 'USDT']);
+// Overridable per-operator via `platformConfig.wallet.cryptoCurrencies` - see `railFor`.
+const DEFAULT_CRYPTO_CURRENCIES = new Set(['BTC', 'ETH', 'USDT', 'USDC']);
+// Mirrors the `wallet.currency` column default: what a player without a wallet row
+// reads as their active currency before one is created on first deposit.
+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';
+export function railFor(currency, cryptoCurrencies) {
+    const set = cryptoCurrencies
+        ? new Set(cryptoCurrencies.map((c) => c.toUpperCase()))
+        : DEFAULT_CRYPTO_CURRENCIES;
+    return set.has(currency.toUpperCase()) ? 'crypto' : 'fiat';
+}
+// Currency checks elsewhere are case-insensitive, so `usd` reaches here for a `USD`
+// wallet. Every read and write of wallet_balance funnels through these three helpers,
+// so normalizing the key here is enough to keep one row per wallet+currency.
+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';
 }
 // 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
@@ -39,72 +81,144 @@ function namespacedIdempotencyKey(namespace, rawKey) {
 }
 // ponytail: a flat, currency-agnostic threshold - a starter heuristic for the review
 // queue, not a compliance risk engine. Revisit with a real risk service if/when one exists.
-const LARGE_WITHDRAWAL_THRESHOLD = 5000;
+// moneyToNumber is the sanctioned JS conversion point for this heuristic comparison only.
+const LARGE_WITHDRAWAL_THRESHOLD = '5000';
 // ponytail: >=3 withdrawals in a 24h window flags velocity; a flat count, not a per-tier rule.
 const HIGH_FREQUENCY_WINDOW_MS = 24 * 60 * 60 * 1000;
 const HIGH_FREQUENCY_MIN_COUNT = 3;
 const DAILY_CAP_WINDOW_MS = 24 * 60 * 60 * 1000;
 // Also the marker the cumulative-cap query reads back to identify auto-approved payouts - keep write and read in lockstep.
 const AUTO_APPROVED_REASON = 'auto-approved';
+function toDepositAddressResult(row) {
+    return {
+        address: row.address,
+        currency: row.currency,
+        ...(row.network === null ? {} : { network: row.network }),
+        ...(row.tag === null ? {} : { tag: row.tag }),
+    };
+}
 function toAutoWithdrawalRuleDto(row) {
     return {
         id: row.id,
         userId: row.userId,
-        threshold: Number(row.threshold),
+        threshold: row.threshold,
         reason: row.reason,
         createdBy: row.createdBy,
         createdAt: row.createdAt.toISOString(),
         updatedAt: row.updatedAt.toISOString(),
     };
 }
+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(),
+    };
+}
 // 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';
 }
+/**
+ * Owns all wallet balance mutations and the withdrawal review/auto-approval
+ * pipeline. Every balance change is a transactional, idempotent-keyed ledger
+ * write (never a bare balance update) - `amount` is always a decimal string,
+ * mutated via SQL numeric arithmetic, never a JS float. Domain events emit only
+ * AFTER the owning transaction commits, and only for the non-replay branch of
+ * an idempotent call.
+ */
 export class WalletService {
     drizzle;
     events;
     payment;
+    identityReader;
     directory;
     platformConfig;
     limiter;
     riskTags;
+    tagEvaluationCommands;
     audit;
-    constructor({ drizzle, events, payment, directory, platformConfig, limiter, riskTags, audit, }) {
+    constructor({ drizzle, events, payment, directory, identityReader, platformConfig, limiter, riskTags, tagEvaluationCommands, audit, }) {
         this.drizzle = drizzle;
         this.events = events;
         this.payment = payment;
         this.directory = directory;
+        this.identityReader = identityReader;
         this.platformConfig = platformConfig;
         this.limiter = limiter;
         this.riskTags = riskTags;
+        this.tagEvaluationCommands = tagEvaluationCommands;
         this.audit = audit;
     }
+    resolveRail(currency) {
+        return railFor(currency, this.platformConfig?.wallet?.cryptoCurrencies);
+    }
     rateLimit(userId) {
         return this.limiter
             ? assertRateLimit(this.limiter, `wallet-mutation:${userId}`, WALLET_MUTATION_RATE_LIMIT)
             : Promise.resolve();
     }
-    /** Fail-closed KYC gate: when enabled, a withdrawal needs a passing status (verified|manually_overridden). */
     async assertKycForWithdrawal(userId) {
-        if (!this.platformConfig?.kyc?.gateWithdrawals)
+        if (!this.platformConfig?.kyc?.gateWithdrawals) {
             return;
+        }
         const status = await this.autoApprovalKycStatus(userId);
-        if (!status || !KYC_PASS_STATUSES.has(status)) {
+        if (!status || !KYC_PASS_STATUSES.has(normalizeKycStatus(status))) {
             throw new KycRequiredError();
         }
     }
     async getBalance(userId) {
         const [record] = await this.drizzle.db.select().from(wallet).where(eq(wallet.userId, userId));
         if (!record) {
-            return { balance: 0, currency: 'USD' };
+            return { balance: '0', currency: DEFAULT_WALLET_CURRENCY };
         }
         return {
-            balance: Number(record.balance),
+            balance: await readWalletBalance(this.drizzle.db, record.id, record.currency),
             currency: record.currency,
         };
     }
+    async getBalances(userId) {
+        const [record] = await this.drizzle.db.select().from(wallet).where(eq(wallet.userId, userId));
+        if (!record) {
+            return { activeCurrency: DEFAULT_WALLET_CURRENCY, balances: [] };
+        }
+        const rows = await this.drizzle.db
+            .select({ currency: walletBalance.currency, balance: walletBalance.amount })
+            .from(walletBalance)
+            .where(eq(walletBalance.walletId, record.id))
+            .orderBy(walletBalance.currency);
+        return { activeCurrency: record.currency, balances: rows };
+    }
+    // TODO: validate `currency` against a canonical supported-currency list once one
+    // exists - `platformConfig.wallet.cryptoCurrencies` classifies rails, it is not an
+    // allowlist, so today any non-empty string is accepted and persisted.
+    async setActiveCurrency(userId, currency) {
+        const updated = await this.drizzle.db
+            .update(wallet)
+            .set({ currency })
+            .where(eq(wallet.userId, userId))
+            .returning({ currency: wallet.currency });
+        const record = updated[0];
+        if (!record) {
+            throw new WalletNotFoundError(userId);
+        }
+        return { activeCurrency: record.currency };
+    }
+    /**
+     * `idempotencyKey` (when supplied) makes a retried deposit a no-op: a replay
+     * returns the original committed result WITHOUT calling the PSP again or
+     * crediting the balance twice, and rejects if the same key is reused with a
+     * different amount/currency (`IdempotencyKeyReuseError`). A GENUINE
+     * concurrent race (two first-attempts, same key, landing at once) can both
+     * reach the PSP, but the ledger insert's unique-index conflict still
+     * guarantees only one balance credit - the loser's write becomes a replay
+     * read of the winner's row.
+     */
     async deposit({ userId, amount, currency, provider, idempotencyKey, }) {
         await this.rateLimit(userId);
         // Short-circuit a replay BEFORE the PSP call - the common retry case (client
@@ -114,10 +228,17 @@ export class WalletService {
         let preResolvedWallet;
         if (idempotencyKey) {
             const found = await this.findDepositReplay({ userId, idempotencyKey, amount, currency });
-            if (found.replay)
+            if (found.replay) {
                 return found.replay;
+            }
             preResolvedWallet = found.walletRecord;
         }
+        else {
+            [preResolvedWallet] = await this.drizzle.db
+                .select()
+                .from(wallet)
+                .where(eq(wallet.userId, userId));
+        }
         const psp = await this.payment.processDeposit(amount, currency, { userId, provider });
         const { transactionId, replayed } = await this.drizzle.db.transaction(async (txn) => {
             let walletRecord = preResolvedWallet;
@@ -125,10 +246,7 @@ export class WalletService {
                 [walletRecord] = await txn.select().from(wallet).where(eq(wallet.userId, userId));
             }
             if (!walletRecord) {
-                [walletRecord] = await txn
-                    .insert(wallet)
-                    .values({ userId, balance: '0', currency })
-                    .returning();
+                walletRecord = findOneOrThrow(await txn.insert(wallet).values({ userId, currency }).returning(), new WalletNotFoundError(userId));
             }
             const { row, replayed } = await this.insertIdempotentTransaction(txn, {
                 namespace: DEPOSIT_IDEMPOTENCY_NAMESPACE,
@@ -139,24 +257,27 @@ export class WalletService {
                 values: {
                     walletId: walletRecord.id,
                     type: 'deposit',
-                    amount: amount.toString(),
+                    amount,
                     currency,
                     status: 'completed',
-                    rail: railFor(currency),
+                    rail: this.resolveRail(currency),
                     providerName: provider,
                     providerRefId: psp.externalId,
                 },
             });
             if (!replayed) {
-                await txn
-                    .update(wallet)
-                    .set({ balance: sql `${wallet.balance} + ${amount}` })
-                    .where(eq(wallet.id, walletRecord.id));
+                await creditWalletBalance(txn, walletRecord.id, currency, amount);
             }
             return { transactionId: row.id, replayed };
         });
         if (!replayed) {
-            this.events.emit('wallet.deposit.completed', { userId, amount, currency, transactionId });
+            this.events.emit('wallet.deposit.completed', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                amount,
+                currency,
+                transactionId,
+            });
         }
         return { transactionId, status: 'completed' };
     }
@@ -167,16 +288,21 @@ export class WalletService {
             .select()
             .from(wallet)
             .where(eq(wallet.userId, userId));
-        if (!walletRecord)
+        if (!walletRecord) {
             return { walletRecord: undefined, replay: undefined };
+        }
         const existing = await this.findByIdempotencyKey(this.drizzle.db, walletRecord.id, namespacedIdempotencyKey(DEPOSIT_IDEMPOTENCY_NAMESPACE, idempotencyKey));
-        if (!existing)
+        if (!existing) {
             return { walletRecord, replay: undefined };
+        }
         this.assertReplayMatches(existing, amount, currency);
         return { walletRecord, replay: { transactionId: existing.id, status: existing.status } };
     }
+    // Replay comparison only (not a ledger write). moneyEquals avoids a false mismatch between
+    // an unnormalized caller string (eg "10") and the DB's fixed-scale value ("10.00") while
+    // staying exact - a float compare would let two amounts differing past the 15th digit pass.
     assertReplayMatches(existing, amount, currency) {
-        if (Number(existing.amount) !== amount ||
+        if (!moneyEquals(existing.amount, amount) ||
             existing.currency.toUpperCase() !== currency.toUpperCase()) {
             throw new IdempotencyKeyReuseError();
         }
@@ -194,8 +320,9 @@ export class WalletService {
         const [row] = idempotencyKey
             ? await insertQuery.onConflictDoNothing().returning()
             : await insertQuery.returning();
-        if (row)
+        if (row) {
             return { row, replayed: false };
+        }
         // Only the keyed (onConflictDoNothing) branch above can return an empty `returning()`
         // - the plain-insert branch always yields exactly one row.
         if (!idempotencyKey) {
@@ -208,17 +335,25 @@ export class WalletService {
         this.assertReplayMatches(winner, amount, currency);
         return { row: winner, replayed: true };
     }
-    /** Creates a PENDING withdrawal and HOLDS the funds (balance debited at request time). Funds are returned on reject/PSP-failure. */
-    async withdraw({ userId, amount, currency, idempotencyKey, }) {
+    /**
+     * Creates a PENDING withdrawal and HOLDS the funds immediately (balance
+     * debited at request time, not on approval) - funds are returned on
+     * reject/PSP-failure. The debit is a conditional `UPDATE ... WHERE balance
+     * >= amount`, atomic with the row lock (`FOR UPDATE`) taken on the wallet,
+     * so two concurrent withdrawals can't both pass a balance check and
+     * double-spend. `idempotencyKey` replay semantics mirror `deposit()`. May
+     * return an already-`completed`/`processing` result if the request
+     * qualifies for (and passes) auto-approval - see `maybeAutoApprove`.
+     */
+    async withdraw({ userId, amount, currency, idempotencyKey, destinationAddress, ip, userAgent, }) {
         await this.rateLimit(userId);
         await this.assertKycForWithdrawal(userId);
+        if (this.resolveRail(currency) === 'crypto' && !destinationAddress) {
+            throw new DestinationAddressRequiredError();
+        }
         const { transactionId, status, replayed, walletId, rail } = await this.drizzle.db.transaction(async (txn) => {
             // FOR UPDATE serializes concurrent withdrawals against a double-debit TOCTOU under READ COMMITTED.
             const current = findOneOrThrow(await txn.select().from(wallet).where(eq(wallet.userId, userId)).for('update'), new WalletNotFoundError(userId));
-            // Single-currency wallet: reject a mismatch rather than coerce it onto the wrong rail.
-            if (currency.toUpperCase() !== current.currency.toUpperCase()) {
-                throw new CurrencyMismatchError(currency, current.currency);
-            }
             // Replay of an already-committed key: return the original untouched. The new-key race is caught by the insert below.
             if (idempotencyKey) {
                 const existing = await this.findByIdempotencyKey(txn, current.id, namespacedIdempotencyKey(WITHDRAW_IDEMPOTENCY_NAMESPACE, idempotencyKey));
@@ -229,7 +364,7 @@ export class WalletService {
                         status: existing.status,
                         replayed: true,
                         walletId: current.id,
-                        rail: railFor(currency),
+                        rail: this.resolveRail(currency),
                     };
                 }
             }
@@ -242,10 +377,11 @@ export class WalletService {
                 values: {
                     walletId: current.id,
                     type: 'withdrawal',
-                    amount: amount.toString(),
+                    amount,
                     currency,
                     status: 'pending',
-                    rail: railFor(currency),
+                    rail: this.resolveRail(currency),
+                    destinationAddress: destinationAddress ?? null,
                 },
             });
             if (replayed) {
@@ -254,29 +390,37 @@ export class WalletService {
                     status: row.status,
                     replayed,
                     walletId: current.id,
-                    rail: railFor(currency),
+                    rail: this.resolveRail(currency),
                 };
             }
             // Guarded conditional debit: the WHERE makes balance>=amount atomic with the write; 0 rows back rolls back the whole tx.
-            const debited = await txn
-                .update(wallet)
-                .set({ balance: sql `${wallet.balance} - ${amount}` })
-                .where(and(eq(wallet.id, current.id), gte(wallet.balance, amount.toString())))
-                .returning({ id: wallet.id });
+            const debited = await debitWalletBalance(txn, current.id, currency, amount);
             if (debited.length !== 1) {
-                throw new InsufficientBalanceError(Number(current.balance), amount);
+                throw new InsufficientBalanceError(await readWalletBalance(txn, current.id, currency), amount);
+            }
+            if (this.tagEvaluationCommands) {
+                await this.tagEvaluationCommands.evaluateWithdrawalRequested(txn, { userId, amount });
             }
             return {
                 transactionId: row.id,
                 status: row.status,
                 replayed,
                 walletId: current.id,
-                rail: railFor(currency),
+                rail: this.resolveRail(currency),
             };
         });
-        if (replayed)
+        if (replayed) {
             return { transactionId, status };
-        this.events.emit('wallet.withdrawal.requested', { userId, amount, currency, transactionId });
+        }
+        this.events.emit('wallet.withdrawal.requested', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            amount,
+            currency,
+            transactionId,
+            ip: ip ?? null,
+            userAgent: userAgent ?? null,
+        });
         // Fail-closed post-step: decides who approves (system vs manual queue), never throws out of withdraw() - failure leaves the row pending.
         const auto = await this.maybeAutoApprove({
             userId,
@@ -292,17 +436,20 @@ export class WalletService {
         const db = this.drizzle.db;
         const { page, limit } = filters;
         const conditions = [eq(walletTransaction.type, 'withdrawal')];
-        if (filters.status)
+        if (filters.status) {
             conditions.push(eq(walletTransaction.status, filters.status));
-        if (filters.currency)
+        }
+        if (filters.currency) {
             conditions.push(eq(walletTransaction.currency, filters.currency));
-        if (filters.rail)
+        }
+        if (filters.rail) {
             conditions.push(eq(walletTransaction.rail, filters.rail));
+        }
         if (filters.minAmount !== undefined) {
-            conditions.push(gte(walletTransaction.amount, filters.minAmount.toString()));
+            conditions.push(gte(walletTransaction.amount, filters.minAmount));
         }
         if (filters.maxAmount !== undefined) {
-            conditions.push(lte(walletTransaction.amount, filters.maxAmount.toString()));
+            conditions.push(lte(walletTransaction.amount, filters.maxAmount));
         }
         if (filters.dateFrom) {
             conditions.push(gte(walletTransaction.createdAt, new Date(filters.dateFrom)));
@@ -312,19 +459,40 @@ export class WalletService {
         }
         // Bounded queue: fetch all SQL-matching rows, then enrich + kycStatus-filter + paginate in memory,
         // else DB-side pagination makes `total` wrong once kycStatus prunes.
+        const wdSortBy = filters.sortBy ?? 'createdAt';
+        const wdDir = (filters.sortOrder ?? 'desc') === 'asc' ? asc : desc;
+        const WD_SORT_COLS = {
+            createdAt: walletTransaction.createdAt,
+            amount: walletTransaction.amount,
+            status: walletTransaction.status,
+            currency: walletTransaction.currency,
+            rail: walletTransaction.rail,
+            reviewedAt: walletTransaction.reviewedAt,
+        };
         const rows = await db
             .select({ tx: walletTransaction, userId: wallet.userId })
             .from(walletTransaction)
             .innerJoin(wallet, eq(wallet.id, walletTransaction.walletId))
             .where(and(...conditions))
-            .orderBy(desc(walletTransaction.createdAt));
+            .orderBy(wdDir(WD_SORT_COLS[wdSortBy]), desc(walletTransaction.id));
         const userIds = [...new Set(rows.map((r) => r.userId))];
         const summaries = this.directory ? await this.directory.lookupPlayers(userIds) : [];
         const byUserId = new Map(summaries.map((s) => [s.userId, s]));
-        const matching = filters.kycStatus
-            ? rows.filter((r) => byUserId.get(r.userId)?.kycStatus === filters.kycStatus)
+        // Normalize both sides before comparing: the ADMIN_USER_DIRECTORY port's return type
+        // still permits the deprecated `verified` value (it aliases `approved`), and this
+        // module cannot assume every bound implementation already normalized it at its own
+        // read boundary - a raw `===` here would silently hide every legacy-verified player
+        // from the queue the moment an admin filters by the canonical `approved`.
+        const kycStatusFilter = filters.kycStatus ? normalizeKycStatus(filters.kycStatus) : undefined;
+        const matching = kycStatusFilter
+            ? rows.filter((r) => {
+                const kycStatus = byUserId.get(r.userId)?.kycStatus;
+                return kycStatus !== undefined && kycStatus !== null
+                    ? normalizeKycStatus(kycStatus) === kycStatusFilter
+                    : false;
+            })
             : rows;
-        const start = (page - 1) * limit;
+        const start = pageToOffset(page, limit);
         const pageRows = matching.slice(start, start + limit);
         // One batched velocity query for the page (no N+1); shares the window + threshold + query the auto-approval evaluator uses.
         const pageWalletIds = [...new Set(pageRows.map((r) => r.tx.walletId))];
@@ -332,21 +500,26 @@ export class WalletService {
         const items = pageRows.map((r) => {
             const summary = byUserId.get(r.userId);
             const riskTags = [];
-            if (Number(r.tx.amount) >= LARGE_WITHDRAWAL_THRESHOLD)
+            if (moneyToNumber(r.tx.amount) >= moneyToNumber(LARGE_WITHDRAWAL_THRESHOLD)) {
                 riskTags.push('large_amount');
-            if (frequentWalletIds.has(r.tx.walletId))
+            }
+            if (frequentWalletIds.has(r.tx.walletId)) {
                 riskTags.push('high_frequency');
+            }
             return {
                 transactionId: r.tx.id,
                 userId: r.userId,
+                playerId: summary?.playerId ?? null,
                 username: summary?.username ?? '',
-                amount: Number(r.tx.amount),
+                amount: r.tx.amount,
                 currency: r.tx.currency,
                 rail: r.tx.rail ?? null,
                 status: r.tx.status,
                 kycStatus: summary?.kycStatus ?? null,
                 riskTags,
                 requestedAt: r.tx.createdAt.toISOString(),
+                destinationAddress: r.tx.destinationAddress,
+                txHash: r.tx.txHash,
             };
         });
         return { items, total: matching.length, page, limit };
@@ -356,11 +529,11 @@ export class WalletService {
      * or Failed + refund on PSP error. Robust PSP idempotency-key/reconciliation for a
      * lost-response is deferred - same scope boundary the deposit path declares.
      */
-    async approveWithdrawal(adminId, withdrawalId) {
+    async approveWithdrawal(adminId, withdrawalId, meta) {
         // Two-phase: commit the `processing` flip first (FOR UPDATE lock), then call the PSP OUTSIDE
         // the tx (a failure refunds in a second tx). Never inline the PSP call inside the hold transaction.
         const tx = await this.drizzle.db.transaction((txn) => this.flipToProcessing({ txn, withdrawalId, adminId }));
-        return this.settleApproved(tx, adminId);
+        return this.settleApproved(tx, adminId, meta);
     }
     // Phase one: the pending -> processing flip under a FOR UPDATE lock. Extracted so the auto path can run it
     // inside its advisory-locked cap-check transaction, committing the marker atomically. Never call the PSP here.
@@ -374,7 +547,7 @@ export class WalletService {
         if (current.status !== 'pending' || current.type !== 'withdrawal') {
             throw new WithdrawalNotPendingError();
         }
-        const [updated] = await txn
+        return findOneOrThrow(await txn
             .update(walletTransaction)
             .set({
             status: 'processing',
@@ -383,14 +556,13 @@ export class WalletService {
             ...(reviewReason !== undefined ? { reviewReason } : {}),
         })
             .where(eq(walletTransaction.id, withdrawalId))
-            .returning();
-        return updated;
+            .returning(), new WithdrawalNotFoundError(withdrawalId));
     }
     // Phase two: settle a `processing` withdrawal via the PSP (Completed on success, Failed + refund on error).
     // Runs OUTSIDE the hold/flip transaction so the external PSP call never holds a DB lock.
-    async settleApproved(tx, adminId) {
+    async settleApproved(tx, adminId, meta) {
         const userId = await this.userIdForWallet(tx.walletId);
-        const amount = Number(tx.amount);
+        const amount = tx.amount;
         // approved/failed are admin-attributed events (schema requires a uuid adminId); the system auto path
         // skips them - its trail is the AUDIT_WRITER entry plus the shared `completed` event below.
         if (adminId) {
@@ -400,6 +572,8 @@ export class WalletService {
                 currency: tx.currency,
                 transactionId: tx.id,
                 adminId,
+                ip: meta?.ip ?? null,
+                userAgent: meta?.userAgent ?? null,
             });
         }
         let result;
@@ -409,31 +583,25 @@ export class WalletService {
                 userId,
                 rail: tx.rail,
                 adminId,
+                destinationAddress: tx.destinationAddress,
             });
         }
         catch (err) {
             // Payout did not happen - mark failed and return the held funds in one transaction.
-            await this.drizzle.db.transaction(async (txn) => {
-                await txn
-                    .update(walletTransaction)
-                    .set({ status: 'failed' })
-                    .where(eq(walletTransaction.id, tx.id));
-                await txn
-                    .update(wallet)
-                    .set({ balance: sql `${wallet.balance} + ${amount}` })
-                    .where(eq(wallet.id, tx.walletId));
-            });
-            if (adminId) {
-                this.events.emit('wallet.withdrawal.failed', {
-                    userId,
-                    amount,
-                    currency: tx.currency,
-                    transactionId: tx.id,
-                    adminId,
-                });
-            }
+            await this.finalizeFailedWithdrawal({ tx, adminId, userId, amount });
             throw err;
         }
+        if (result.status === 'failed') {
+            await this.finalizeFailedWithdrawal({ tx, adminId, userId, amount });
+            return { transactionId: tx.id, status: 'failed' };
+        }
+        if (result.status !== 'completed') {
+            await this.drizzle.db
+                .update(walletTransaction)
+                .set({ providerName: providerNameFor(tx.rail), providerRefId: result.externalId })
+                .where(eq(walletTransaction.id, tx.id));
+            return { transactionId: tx.id, status: 'processing' };
+        }
         await this.drizzle.db
             .update(walletTransaction)
             .set({
@@ -444,32 +612,94 @@ export class WalletService {
             .where(eq(walletTransaction.id, tx.id));
         this.events.emit('wallet.withdrawal.completed', {
             userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
             amount,
             currency: tx.currency,
             transactionId: tx.id,
         });
         return { transactionId: tx.id, status: 'completed' };
     }
+    async finalizeFailedWithdrawal({ tx, adminId, userId, amount, }) {
+        const transitioned = await this.drizzle.db.transaction(async (txn) => {
+            const updated = await txn
+                .update(walletTransaction)
+                .set({ status: 'failed' })
+                .where(and(eq(walletTransaction.id, tx.id), eq(walletTransaction.status, 'processing')))
+                .returning({ id: walletTransaction.id });
+            if (updated.length === 0) {
+                return false;
+            }
+            await creditWalletBalance(txn, tx.walletId, tx.currency, amount);
+            return true;
+        });
+        if (transitioned && adminId) {
+            this.events.emit('wallet.withdrawal.failed', {
+                userId,
+                amount,
+                currency: tx.currency,
+                transactionId: tx.id,
+                adminId,
+            });
+        }
+    }
+    async reconcileWithdrawalStatus(event) {
+        const { externalId, status, txHash } = event;
+        const [tx] = await this.drizzle.db
+            .select()
+            .from(walletTransaction)
+            .where(eq(walletTransaction.providerRefId, externalId));
+        if (!tx || tx.type !== 'withdrawal') {
+            logger.warn({ externalId }, 'payment webhook: no matching withdrawal for providerRefId');
+            return;
+        }
+        if (tx.status !== 'processing') {
+            return;
+        }
+        const userId = await this.userIdForWallet(tx.walletId);
+        if (status === 'completed') {
+            const updated = await this.drizzle.db
+                .update(walletTransaction)
+                .set({ status: 'completed', txHash: txHash ?? tx.txHash })
+                .where(and(eq(walletTransaction.id, tx.id), eq(walletTransaction.status, 'processing')))
+                .returning({ id: walletTransaction.id });
+            if (updated.length === 0) {
+                return;
+            }
+            this.events.emit('wallet.withdrawal.completed', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                amount: tx.amount,
+                currency: tx.currency,
+                transactionId: tx.id,
+            });
+            return;
+        }
+        if (status === 'failed') {
+            await this.finalizeFailedWithdrawal({ tx, adminId: null, userId, amount: tx.amount });
+        }
+    }
     // Evaluates the auto-approval gates and settles the payout if all pass; returns undefined to
     // leave the row pending for the manual queue. NEVER throws: any error fails closed to manual.
     async maybeAutoApprove(args) {
-        // Cheap gates first (auto-approval off, or crypto - never auto-approved): skip opening a tx/lock.
-        if (!this.platformConfig?.autoWithdrawal?.enabled || args.rail !== 'fiat')
+        if (!this.platformConfig?.autoWithdrawal?.enabled) {
             return undefined;
+        }
         try {
             const cfg = this.platformConfig.autoWithdrawal;
             // Threshold/KYC/risk/velocity gates run outside any lock; only the cap check below needs serializing.
             const gates = await this.evaluateAutoApproval(args);
-            if (!gates)
+            if (!gates) {
                 return undefined;
+            }
             // Serialize the cap-check-and-flip per user with an advisory lock: without it two concurrent
             // withdrawals read the same daily-cap usage and both auto-approve, bypassing the cap. The cap read
             // and the flip that writes the marker commit together, so a blocked caller re-reads current usage.
             // PSP settlement runs AFTER, outside the lock.
             const decided = await this.drizzle.db.transaction((txn) => withAdvisoryXactLock(txn, args.userId, async () => {
                 const caps = await this.autoApprovalCaps({ walletId: args.walletId, amount: args.amount, cfg }, txn);
-                if (caps.exceeded)
+                if (caps.exceeded) {
                     return null;
+                }
                 const tx = await this.flipToProcessing({
                     txn,
                     withdrawalId: args.transactionId,
@@ -478,8 +708,9 @@ export class WalletService {
                 });
                 return { tx, caps };
             }));
-            if (!decided)
+            if (!decided) {
                 return undefined;
+            }
             const decision = {
                 ...gates,
                 dailyCapAmount: cfg.dailyCapAmount ?? null,
@@ -494,7 +725,12 @@ export class WalletService {
                     action: 'wallet.withdrawal.auto_approved',
                     resourceType: 'wallet_transaction',
                     resourceId: args.transactionId,
-                    after: { userId: args.userId, amount: args.amount, currency: args.currency, ...decision },
+                    after: {
+                        userId: args.userId,
+                        amount: args.amount,
+                        currency: args.currency,
+                        ...decision,
+                    },
                 });
             }
             catch (err) {
@@ -518,69 +754,153 @@ export class WalletService {
     // route to manual. The daily-cap check is NOT here - it runs under the advisory lock (see maybeAutoApprove).
     async evaluateAutoApproval({ userId, amount, walletId, rail, }) {
         const cfg = this.platformConfig?.autoWithdrawal;
-        if (!cfg?.enabled)
+        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);
-        if (!threshold || threshold.value <= 0)
+        }
+        const threshold = await this.resolveAutoThreshold(userId, rail);
+        if (!threshold || moneyToNumber(threshold.value) <= 0) {
             return null;
-        if (amount > threshold.value)
+        }
+        if (moneyToNumber(amount) > moneyToNumber(threshold.value)) {
             return null;
+        }
         // Independent of kyc.gateWithdrawals: auto-approval always demands a passing status; anything else fails closed.
         const kycStatus = await this.autoApprovalKycStatus(userId);
-        if (!kycStatus || !KYC_PASS_STATUSES.has(kycStatus))
+        if (!kycStatus || !KYC_PASS_STATUSES.has(normalizeKycStatus(kycStatus))) {
             return null;
-        const riskTags = await this.autoApprovalRiskTags(userId, cfg.excludeRiskFlags);
+        }
+        const effectiveExcludeTags = threshold.config.excludeRiskFlags;
+        const riskTags = await this.autoApprovalRiskTags(userId, effectiveExcludeTags);
         // null = exclusions configured but the lookup port is unavailable => fail closed.
-        if (riskTags === null)
+        if (riskTags === null) {
             return null;
-        if (riskTags.some((t) => cfg.excludeRiskFlags.includes(t)))
+        }
+        if (riskTags.some((t) => effectiveExcludeTags.includes(t))) {
             return null;
+        }
         const heuristics = await this.autoApprovalHeuristics({ walletId, amount });
-        if (heuristics.largeAmount || heuristics.highFrequency)
+        if (heuristics.largeAmount || heuristics.highFrequency) {
             return null;
+        }
         return {
             threshold: threshold.value,
             thresholdSource: threshold.source,
             kycStatus,
             riskTagsEvaluated: riskTags,
+            effectiveExcludeTags,
         };
     }
-    // Per-player rule wins over the global fiat threshold; null when neither is set.
-    async resolveAutoThreshold(userId) {
+    async resolveAutoThreshold(userId, rail) {
+        // Always read the global singleton first, even when a per-player override may end up
+        // winning below - an unseeded install (missing row) must fail closed for EVERY player,
+        // not just those without an override. getAutoWithdrawalConfig() throws when absent.
+        const config = await this.getAutoWithdrawalConfig();
         const [rule] = await this.drizzle.db
             .select()
             .from(autoWithdrawalRule)
             .where(eq(autoWithdrawalRule.userId, userId));
-        if (rule)
-            return { value: Number(rule.threshold), source: 'per-player' };
-        const global = this.platformConfig?.autoWithdrawal?.fiatThreshold;
-        if (global !== undefined)
-            return { value: global, source: 'global' };
-        return null;
+        if (rule) {
+            return { value: rule.threshold, source: 'per-player', config };
+        }
+        const global = rail === 'crypto' ? config.cryptoThreshold : config.fiatThreshold;
+        return { value: global, source: 'global', config };
+    }
+    // The row always exists in a properly-seeded install (seeded once) - a
+    // missing row is an unexpected failure mode on the READ path, not a normal
+    // "unconfigured" state, so this throws rather than silently defaulting.
+    // maybeAutoApprove's outer try/catch handles that thrown error the same as any
+    // other unexpected error: fail closed to pending.
+    async getAutoWithdrawalConfig() {
+        const config = await this.getAutoWithdrawalConfigOrNull();
+        if (!config) {
+            throw new AutoWithdrawalConfigNotFoundError('global');
+        }
+        return config;
+    }
+    // Non-throwing variant for callers that need to tell "missing" from "found"
+    // without a try/catch (eg the router's audit `before` read).
+    async getAutoWithdrawalConfigOrNull() {
+        const [row] = await this.drizzle.db
+            .select()
+            .from(walletAutoWithdrawalConfig)
+            .where(eq(walletAutoWithdrawalConfig.singletonKey, 'global'));
+        return row ? toAutoWithdrawalConfigDto(row) : null;
+    }
+    // Upsert, not a plain UPDATE: the WRITE path lets a Super Admin self-heal a
+    // missing singleton row (eg an install that skipped the seed step) through the
+    // existing route with zero new surface. The READ path (getAutoWithdrawalConfig,
+    // resolveAutoThreshold) still throws on a missing row and stays fail-closed -
+    // a withdrawal must never silently create config.
+    //
+    // Update + audit write run in one transaction: an audit-write failure must roll back
+    // the threshold change too, or the config could change with no audit trail.
+    async setAutoWithdrawalConfig(adminId, { fiatThreshold, cryptoThreshold, excludeRiskFlags, }, meta) {
+        return this.drizzle.db.transaction(async (txn) => {
+            const [before] = await txn
+                .select()
+                .from(walletAutoWithdrawalConfig)
+                .where(eq(walletAutoWithdrawalConfig.singletonKey, 'global'));
+            const rows = await txn
+                .insert(walletAutoWithdrawalConfig)
+                .values({
+                singletonKey: 'global',
+                fiatThreshold,
+                cryptoThreshold,
+                excludeRiskFlags,
+                updatedBy: adminId,
+            })
+                .onConflictDoUpdate({
+                target: walletAutoWithdrawalConfig.singletonKey,
+                set: { fiatThreshold, cryptoThreshold, excludeRiskFlags, updatedBy: adminId },
+            })
+                .returning();
+            const config = toAutoWithdrawalConfigDto(findOneOrThrow(rows, new AutoWithdrawalConfigNotFoundError('global')));
+            await this.audit.recordInTransaction(txn, {
+                actorId: adminId,
+                actorType: 'admin',
+                action: 'wallet.auto_withdrawal_config.set',
+                resourceType: 'auto_withdrawal_config',
+                resourceId: config.id,
+                before: before
+                    ? {
+                        fiatThreshold: before.fiatThreshold,
+                        cryptoThreshold: before.cryptoThreshold,
+                        excludeRiskFlags: before.excludeRiskFlags,
+                    }
+                    : null,
+                after: {
+                    fiatThreshold: config.fiatThreshold,
+                    cryptoThreshold: config.cryptoThreshold,
+                    excludeRiskFlags: config.excludeRiskFlags,
+                },
+                ...meta,
+            });
+            return config;
+        });
     }
     async autoApprovalKycStatus(userId) {
         // No directory bound => cannot verify KYC => fail closed.
-        if (!this.directory)
+        if (!this.directory) {
             return null;
+        }
         const [summary] = await this.directory.lookupPlayers([userId]);
         return summary?.kycStatus ?? null;
     }
     // Active tag keys; [] when no exclusions configured or none carried; null when configured but the port is unbound (fail closed).
     async autoApprovalRiskTags(userId, excludeRiskFlags) {
-        if (excludeRiskFlags.length === 0)
+        if (excludeRiskFlags.length === 0) {
             return [];
-        if (!this.riskTags)
+        }
+        if (!this.riskTags) {
             return null;
+        }
         const byUser = await this.riskTags.getActiveTagKeys([userId]);
         return byUser.get(userId) ?? [];
     }
     async autoApprovalHeuristics({ walletId, amount, }) {
         const frequent = await this.frequentWithdrawalWalletIds(this.drizzle.db, [walletId]);
         return {
-            largeAmount: amount >= LARGE_WITHDRAWAL_THRESHOLD,
+            largeAmount: moneyToNumber(amount) >= moneyToNumber(LARGE_WITHDRAWAL_THRESHOLD),
             highFrequency: frequent.has(walletId),
         };
     }
@@ -588,8 +908,9 @@ export class WalletService {
     // Single source of the velocity check, shared by the review queue tag and the auto-approval heuristic.
     async frequentWithdrawalWalletIds(db, walletIds) {
         const frequent = new Set();
-        if (walletIds.length === 0)
+        if (walletIds.length === 0) {
             return frequent;
+        }
         const since = new Date(Date.now() - HIGH_FREQUENCY_WINDOW_MS);
         const counts = await db
             .select({ walletId: walletTransaction.walletId, n: count() })
@@ -597,8 +918,9 @@ export class WalletService {
             .where(and(eq(walletTransaction.type, 'withdrawal'), gte(walletTransaction.createdAt, since), inArray(walletTransaction.walletId, walletIds)))
             .groupBy(walletTransaction.walletId);
         for (const row of counts) {
-            if (Number(row.n) >= HIGH_FREQUENCY_MIN_COUNT)
+            if (Number(row.n) >= HIGH_FREQUENCY_MIN_COUNT) {
                 frequent.add(row.walletId);
+            }
         }
         return frequent;
     }
@@ -607,24 +929,30 @@ export class WalletService {
     async autoApprovalCaps({ walletId, amount, cfg, }, db) {
         const since = new Date(Date.now() - DAILY_CAP_WINDOW_MS);
         const [row] = await db
-            .select({ total: sql `coalesce(sum(${walletTransaction.amount}), 0)`, n: count() })
+            .select({
+            total: sql `coalesce(sum(${walletTransaction.amount}), 0)`,
+            n: count(),
+        })
             .from(walletTransaction)
             .where(and(eq(walletTransaction.walletId, walletId), eq(walletTransaction.type, 'withdrawal'), eq(walletTransaction.reviewReason, AUTO_APPROVED_REASON), gte(walletTransaction.createdAt, since)));
-        const amountUsed = Number(row?.total ?? 0);
+        const amountUsed = row?.total ?? '0';
         const countUsed = Number(row?.n ?? 0);
-        const amountExceeded = cfg.dailyCapAmount !== undefined && amountUsed + amount > cfg.dailyCapAmount;
+        // Cap comparison is a review-queue decision, not a ledger write - moneyToNumber is the
+        // documented single conversion point (see the helper's own doc comment).
+        const amountExceeded = cfg.dailyCapAmount !== undefined &&
+            moneyToNumber(amountUsed) + moneyToNumber(amount) > moneyToNumber(cfg.dailyCapAmount);
         const countExceeded = cfg.dailyCapCount !== undefined && countUsed + 1 > cfg.dailyCapCount;
         return { exceeded: amountExceeded || countExceeded, amountUsed, countUsed };
     }
     async setAutoWithdrawalRule({ userId, threshold, reason, createdBy, }) {
-        const [row] = await this.drizzle.db
+        const row = findOneOrThrow(await this.drizzle.db
             .insert(autoWithdrawalRule)
-            .values({ userId, threshold: threshold.toString(), reason, createdBy })
+            .values({ userId, threshold, reason, createdBy })
             .onConflictDoUpdate({
             target: autoWithdrawalRule.userId,
-            set: { threshold: threshold.toString(), reason, createdBy },
+            set: { threshold, reason, createdBy },
         })
-            .returning();
+            .returning(), new WalletNotFoundError(userId));
         return toAutoWithdrawalRuleDto(row);
     }
     async getAutoWithdrawalRule(userId) {
@@ -641,7 +969,7 @@ export class WalletService {
             .returning({ id: autoWithdrawalRule.id });
         return deleted.length > 0;
     }
-    async rejectWithdrawal(adminId, withdrawalId, reason) {
+    async rejectWithdrawal(adminId, withdrawalId, reason, meta) {
         const reviewedAt = new Date();
         const tx = await this.drizzle.db.transaction(async (txn) => {
             const current = findOneOrThrow(await txn
@@ -652,40 +980,51 @@ export class WalletService {
             if (current.status !== 'pending' || current.type !== 'withdrawal') {
                 throw new WithdrawalNotPendingError();
             }
-            const [updated] = await txn
+            const updated = findOneOrThrow(await txn
                 .update(walletTransaction)
                 .set({ status: 'rejected', reviewedBy: adminId, reviewedAt, reviewReason: reason })
                 .where(eq(walletTransaction.id, withdrawalId))
-                .returning();
-            await txn
-                .update(wallet)
-                .set({ balance: sql `${wallet.balance} + ${updated.amount}` })
-                .where(eq(wallet.id, updated.walletId));
+                .returning(), new WithdrawalNotFoundError(withdrawalId));
+            await creditWalletBalance(txn, updated.walletId, updated.currency, updated.amount);
             return updated;
         });
         const userId = await this.userIdForWallet(tx.walletId);
         this.events.emit('wallet.withdrawal.rejected', {
             userId,
-            amount: Number(tx.amount),
+            amount: tx.amount,
             currency: tx.currency,
             transactionId: tx.id,
             adminId,
             reason,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
         });
         return { transactionId: tx.id, status: 'rejected' };
     }
-    async getTransactions(userId, page, limit) {
+    async getTransactions({ userId, page, limit, sortBy, sortOrder, }) {
         const db = this.drizzle.db;
         const [walletRecord] = await db.select().from(wallet).where(eq(wallet.userId, userId));
-        if (!walletRecord)
+        if (!walletRecord) {
             return { items: [], total: 0, page, limit };
+        }
+        const dir = (sortOrder ?? 'desc') === 'asc' ? asc : desc;
+        const TX_SORT_COLS = {
+            createdAt: walletTransaction.createdAt,
+            amount: walletTransaction.amount,
+            type: walletTransaction.type,
+            status: walletTransaction.status,
+            currency: walletTransaction.currency,
+            rail: walletTransaction.rail,
+            reviewedAt: walletTransaction.reviewedAt,
+        };
+        const col = TX_SORT_COLS[sortBy ?? 'createdAt'];
         const where = eq(walletTransaction.walletId, walletRecord.id);
         const [txs, [{ n }]] = await Promise.all([
             db
                 .select()
                 .from(walletTransaction)
                 .where(where)
-                .orderBy(desc(walletTransaction.createdAt))
+                .orderBy(dir(col), desc(walletTransaction.id))
                 .limit(limit)
                 .offset(pageToOffset(page, limit)),
             db.select({ n: count() }).from(walletTransaction).where(where),
@@ -694,7 +1033,7 @@ export class WalletService {
             items: txs.map((tx) => ({
                 id: tx.id,
                 type: tx.type,
-                amount: Number(tx.amount),
+                amount: tx.amount,
                 currency: tx.currency,
                 status: tx.status,
                 createdAt: tx.createdAt.toISOString(),
@@ -704,6 +1043,96 @@ export class WalletService {
             limit,
         };
     }
+    async getOrCreateDepositAddress(userId, currency, network) {
+        const existing = await this.findDepositAddress(userId, currency, network);
+        if (existing) {
+            return toDepositAddressResult(existing);
+        }
+        if (!this.payment.issueDepositAddress) {
+            throw new DepositAddressUnsupportedError();
+        }
+        const issued = await this.payment.issueDepositAddress(userId, currency, network);
+        const [row] = await this.drizzle.db
+            .insert(walletDepositAddress)
+            .values({
+            userId,
+            currency,
+            network: network ?? null,
+            address: issued.address,
+            tag: issued.tag ?? null,
+            providerName: providerNameFor(this.resolveRail(currency)),
+        })
+            .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);
+    }
+    async creditDepositByAddress(event) {
+        const depositAddress = await this.findDepositAddressByAddress(event);
+        if (!depositAddress) {
+            logger.warn({ address: event.address, network: event.network, tag: event.tag }, 'payment webhook: no wallet_deposit_address for inbound deposit');
+            return;
+        }
+        if (event.network === undefined &&
+            event.currency.toUpperCase() !== depositAddress.currency.toUpperCase()) {
+            throw new CurrencyMismatchError(event.currency, depositAddress.currency);
+        }
+        const { transactionId, replayed } = await this.drizzle.db.transaction(async (txn) => {
+            let [walletRecord] = await txn
+                .select()
+                .from(wallet)
+                .where(eq(wallet.userId, depositAddress.userId));
+            if (!walletRecord) {
+                walletRecord = findOneOrThrow(await txn
+                    .insert(wallet)
+                    .values({ userId: depositAddress.userId, currency: event.currency })
+                    .returning(), new WalletNotFoundError(depositAddress.userId));
+            }
+            const [inserted] = await txn
+                .insert(walletTransaction)
+                .values({
+                walletId: walletRecord.id,
+                type: 'deposit',
+                amount: event.amount,
+                currency: event.currency,
+                status: 'completed',
+                rail: this.resolveRail(event.currency),
+                providerName: depositAddress.providerName,
+                providerRefId: event.externalId,
+                destinationAddress: event.address,
+                txHash: event.txHash,
+            })
+                .onConflictDoNothing()
+                .returning();
+            if (inserted) {
+                await creditWalletBalance(txn, walletRecord.id, event.currency, event.amount);
+                return { transactionId: inserted.id, replayed: false };
+            }
+            const [winner] = await txn
+                .select()
+                .from(walletTransaction)
+                .where(eq(walletTransaction.providerRefId, event.externalId));
+            if (!winner) {
+                throw new Error(`payment webhook: idempotency conflict but no row found (externalId=${event.externalId})`);
+            }
+            return { transactionId: winner.id, replayed: true };
+        });
+        if (!replayed) {
+            this.events.emit('wallet.deposit.completed', {
+                userId: depositAddress.userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(depositAddress.userId),
+                amount: event.amount,
+                currency: event.currency,
+                transactionId,
+            });
+        }
+    }
     async userIdForWallet(walletId) {
         const record = findOneOrThrow(await this.drizzle.db
             .select({ userId: wallet.userId })
@@ -718,5 +1147,27 @@ 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];
+    }
 }
 //# sourceMappingURL=wallet.service.js.map