games_app/backend/dist/services/blockchain/tronService.d.ts

122 lines
4.9 KiB
TypeScript

/**
* TRON blockchain integration via TronGrid.
* Read incoming TRX/TRC20 transfers and broadcast outbound transactions.
*/
/** PostgreSQL signed BIGINT upper bound. */
export declare const PG_BIGINT_MAX = 9223372036854775807n;
/**
* Parses a TRC20 transfer `value` from TronGrid into smallest token units.
* Rejects non-decimal strings, floats, negative values, and amounts that do not fit in PG BIGINT.
*/
export declare function parseTrc20TokenAmount(raw: unknown): bigint | null;
/**
* Returns the current TRON block number from the node.
* @returns Latest block height
*/
export declare function getCurrentBlock(): Promise<number>;
/**
* Returns the block timestamp in Unix ms for a given block height.
*/
export declare function getBlockTimestamp(blockNumber: number): Promise<number | null>;
/** Incoming native TRX transfer parsed from TronGrid account transactions. */
export interface TronIncomingTx {
txId: string;
from: string;
to: string;
amount: number;
block: number;
confirmations: number;
}
/**
* Fetches confirmed incoming TRX transfers to an address since an optional timestamp.
* @param address TRON base58 deposit address
* @param minTimestamp Optional minimum block timestamp in ms (filters older txs)
* @returns Parsed incoming transactions with estimated confirmations (~3s per block)
*/
export declare function getTrxTransactionsToAddress(address: string, minTimestamp?: number): Promise<TronIncomingTx[]>;
/** Incoming TRC20 token transfer from TronGrid TRC20 endpoint. */
export interface Trc20Transfer {
txId: string;
from: string;
to: string;
value: string;
block: number;
block_timestamp: number;
/** Confirmations estimated from elapsed time (~3s per block). */
confirmations: number;
}
/**
* Fetches confirmed incoming TRC20 transfers to an address for a given contract.
* @param address TRON base58 deposit address
* @param contractAddress TRC20 contract address (e.g. USDT)
* @param minTimestamp Optional minimum event timestamp in ms
* @returns Transfers where `to` matches the address, with raw token value as string
*/
export declare function getTrc20TransfersToAddress(address: string, contractAddress: string, minTimestamp?: number): Promise<Trc20Transfer[]>;
/**
* Sends native TRX from a hot wallet private key.
* @param fromPrivateKeyHex Sender private key in hex
* @param toAddress Recipient base58 address
* @param amountSun Amount in sun (1 TRX = 1e6 sun)
* @returns Broadcast transaction ID
* @throws {Error} When broadcast returns no txid
*/
export declare function sendTrx(fromPrivateKeyHex: string, toAddress: string, amountSun: bigint): Promise<string>;
/**
* Sends TRC20 tokens via contract transfer from a hot wallet.
* @param fromPrivateKeyHex Sender private key in hex
* @param contractAddress TRC20 contract address
* @param toAddress Recipient base58 address
* @param amountRaw Token amount in smallest unit (string passed to contract)
* @returns Transaction ID from broadcast result
*/
export declare function sendTrc20(fromPrivateKeyHex: string, contractAddress: string, toAddress: string, amountRaw: bigint): Promise<string>;
/** Signed TRC20 payout whose txID is known before it is broadcast. */
export type SignedTronTransfer = {
txId: string;
/** JSON of the signed transaction (re-broadcastable as-is until expiration). */
payload: string;
expiresAt: Date;
fromAddress: string;
};
/**
* Builds and signs a TRC20 `transfer` without broadcasting it.
*/
export declare function signTrc20Transfer(fromPrivateKeyHex: string, contractAddress: string, toAddress: string, amountRaw: bigint): Promise<SignedTronTransfer>;
export type TronBroadcastResult = {
kind: 'accepted';
} | {
kind: 'rejected';
code: string;
message: string;
};
/**
* Interprets a `sendRawTransaction` response. A response with an error code means the node
* refused the transaction (it was not accepted); DUP_TRANSACTION_ERROR means it is already known.
*/
export declare function classifyTronBroadcastResponse(res: {
result?: boolean;
code?: string;
message?: string;
}): TronBroadcastResult;
/** Broadcasts a previously signed payload. Throws only on transport errors (outcome unknown). */
export declare function broadcastSignedTransaction(payload: string): Promise<TronBroadcastResult>;
export type TronTxStatus = {
kind: 'not_found';
} | {
kind: 'mined';
success: boolean;
confirmations: number;
message?: string;
};
/** Looks a payout up by txID on the full node (includes not-yet-solidified blocks). */
export declare function getTransactionStatus(txId: string): Promise<TronTxStatus>;
/**
* Returns native TRX balance in sun for an address.
*/
export declare function getTrxBalanceSun(address: string): Promise<bigint>;
/**
* Returns TRC20 token balance in smallest units for an address.
*/
export declare function getTrc20BalanceRaw(address: string, contractAddress: string): Promise<bigint>;
//# sourceMappingURL=tronService.d.ts.map