games_app/backend/dist/services/withdrawalService.d.ts

86 lines
4.3 KiB
TypeScript

/**
* On-chain withdrawal service (state machine v2).
*
* A valid request is always recorded as `pending` with `amount + fee` reserved on the user's
* unified USDT ledger (USDT_TRC20, 6 decimals), even when the platform hot wallet cannot pay
* right now. Payout runs separately: pending -> processing -> completed once the transaction
* is confirmed on-chain. Platform liquidity problems never surface to the user — the request
* simply stays pending until an admin (or the automatic attempt) processes it.
*/
import type { WithdrawalActor, WithdrawalRow } from '../repositories/withdrawalRepository';
import { WithdrawalPendingReason } from './withdrawals/withdrawalStateMachine';
export type WithdrawalResult = {
transactionId: string;
status: string;
amount: string;
fee: string;
totalDebited: string;
fundRequestId?: string;
blockchainTxId?: string | null;
/** True when the same idempotency key was already used: no new request was created. */
duplicate?: boolean;
};
export type RequestWithdrawalOptions = {
/** Client-generated key: repeating a submission returns the original request. */
idempotencyKey?: string | null;
/** Start payout right after recording (default true). */
autoProcess?: boolean;
};
/**
* Records a withdrawal request: validates, reserves funds and returns status `pending`.
* Never fails because of platform hot-wallet liquidity.
*/
export declare function requestWithdrawal(userId: string, walletTypeCode: string, toAddress: string, amountRaw: bigint, totpCode?: string, options?: RequestWithdrawalOptions): Promise<WithdrawalResult>;
export type ProcessWithdrawalResult = {
transactionId: string;
status: string;
pendingReason?: WithdrawalPendingReason | null;
blockchainTxId?: string | null;
message?: string;
};
/**
* Attempts the payout of a pending/failed request: pending|failed -> processing, then either
* broadcast (stays processing until confirmed), back to pending (liquidity), or failed.
* Throws WithdrawalStateError only when the request cannot be processed from its status.
*/
export declare function processWithdrawal(transactionId: string, actor: WithdrawalActor, opts?: {
approvalGranted?: boolean;
}): Promise<ProcessWithdrawalResult>;
/** Called by the approval workflow once the large-withdrawal quorum is reached. */
export declare function processApprovedWithdrawal(transactionId: string, approvedBy: string): Promise<Record<string, unknown>>;
/** @deprecated name kept for the approval workflow; payout is now asynchronous. */
export declare const broadcastApprovedWithdrawal: typeof processApprovedWithdrawal;
/** Verifies one broadcast payout on-chain and advances its status when the result is known. */
export declare function verifyBroadcastWithdrawal(row: WithdrawalRow, nowMs?: number): Promise<string>;
/**
* Automatic retry pass (only when enabled in settings). A request is claimed only when the
* hot wallet can pay it right now (USDT + gas, minus payouts already in flight), so an
* unfunded wallet produces no status churn.
*/
export declare function runWithdrawalAutoRetryCycle(): Promise<{
attempted: number;
skipped: number;
}>;
/** One pass of the confirmation monitor (also recovers interrupted claims and auto-retries). */
export declare function runWithdrawalMonitorCycle(): Promise<{
checked: number;
completed: number;
}>;
/** Admin refusal (pending|failed -> rejected) with a full, single refund. */
export declare function rejectWithdrawal(transactionId: string, input: {
actorId: string;
reason: string;
source?: 'admin' | 'approval';
}): Promise<WithdrawalRow>;
/** User cancellation of a request that is still pending (pending -> cancelled, refunded). */
export declare function cancelWithdrawal(transactionId: string, input: {
userId: string;
actorType?: 'user' | 'admin';
actorId?: string;
source?: 'user' | 'approval';
}): Promise<WithdrawalRow>;
/** Approval workflow cancelled by the requester / super admin. */
export declare function cancelWithdrawalFromApproval(transactionId: string, actorId: string): Promise<void>;
/** Admin: failed -> pending (e.g. before a later retry). */
export declare function requeueWithdrawal(transactionId: string, actorId: string): Promise<WithdrawalRow>;
//# sourceMappingURL=withdrawalService.d.ts.map