86 lines
4.3 KiB
TypeScript
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
|