crypto-aio 0.0.3 → 0.1.0

package/dist/adapters/tron/http.d.ts

@@ -0,0 +1,173 @@
+import { ProviderError } from '../../core/errors/error';
+import type { Transport } from '../../core/transport/types';
+import type { TronCallTags, TronResources } from './types';
+export declare const READ: TronCallTags;
+export declare const MONITOR: TronCallTags;
+export declare const PROOF: TronCallTags;
+export declare const BROADCAST: TronCallTags;
+/** Adds the caller's signal to a tag set. */
+export declare const withSignal: (tags: TronCallTags, signal?: AbortSignal) => TronCallTags;
+type Json = Record<string, unknown>;
+type QuorumKey = (result: unknown) => unknown;
+export declare function malformed(field: string): ProviderError;
+/**
+ * The node indexed a transaction it cannot serve whole yet (its receipt, the transaction or
+ * its block): neither "not seen" nor a verdict. Retryable; the core keeps its current view.
+ */
+export declare function notServable(): ProviderError;
+/** The consensus facts compared under a quorum for `path`, if it has any. */
+export declare const quorumKeyFor: (path: string) => QuorumKey | undefined;
+export interface TronBlockHeader {
+    readonly number: bigint;
+    readonly id: string;
+    readonly parentId: string;
+    readonly timestamp: number;
+}
+export interface TronLog {
+    /** The emitter, 20-byte hex (no `41`). */
+    readonly address: string;
+    readonly topics: readonly string[];
+    readonly data: string;
+}
+export interface TronTxInfo {
+    readonly id: string;
+    readonly blockNumber: bigint;
+    readonly blockTimestamp: number;
+    /** Total TRX burned, in sun. */
+    readonly fee: bigint;
+    /** `receipt.result` of a contract call (`SUCCESS`, `REVERT`, `OUT_OF_ENERGY`, …). */
+    readonly receiptResult?: string;
+    /** `FAILED` when execution failed. */
+    readonly failed: boolean;
+    readonly logs: readonly TronLog[];
+}
+export interface TronTxJson {
+    readonly id: string;
+    readonly rawHex: string;
+    /** `ret[0].contractRet`, absent while pending. */
+    readonly contractRet?: string;
+}
+export interface ChainParameters {
+    readonly transactionFee: bigint;
+    readonly energyFee: bigint;
+    readonly createAccountFee: bigint;
+    readonly createNewAccountFeeInSystemContract: bigint;
+    readonly createNewAccountBandwidthRate: bigint;
+    readonly memoFee: bigint;
+    readonly maxFeeLimit: bigint;
+    /**
+     * `getForbidTransferToContract` is 1: `TransferActuator` refuses TRX sent to a contract
+     * account. 0 (proto3 JSON omits it) on mainnet, Nile and Shasta, read 2026-09-29.
+     */
+    readonly forbidTransferToContract: boolean;
+}
+export type ConstantCall = {
+    readonly kind: 'ok';
+    readonly result: string;
+    readonly energy: bigint;
+} | {
+    readonly kind: 'failed';
+    readonly energy: bigint;
+} | {
+    readonly kind: 'no-contract';
+};
+export interface BroadcastAnswer {
+    readonly accepted: boolean;
+    readonly code?: string;
+    /** The node's message, decoded when it is hex. Never stored or logged as is. */
+    readonly message?: string;
+}
+export interface RpcBlock {
+    readonly number: bigint;
+    readonly hash: string;
+    readonly parentHash: string;
+    readonly timestamp: number;
+    readonly transactions: readonly string[];
+}
+/**
+ * A node's message field: hex-encoded UTF-8 on some paths, plain text on others. At most
+ * the first 1 KiB is kept, decoded when the whole field is printable hex.
+ */
+export declare function messageText(value: unknown): string | undefined;
+export declare class TronApi {
+    #private;
+    constructor(transport: Transport);
+    /**
+     * One POST to `path`, answered as JSON; a node `Error` answer is a retryable RPC_ERROR
+     * (possibly sent, on a broadcast).
+     */
+    post(path: string, body: Json, tags: TronCallTags): Promise<unknown>;
+    /** The head (`scope: 'full'`) or latest solidified block, or one by height or id. */
+    block(scope: 'full' | 'solid', ref: bigint | string | undefined, tags: TronCallTags): Promise<TronBlockHeader | null>;
+    /**
+     * A block with its transactions and their infos (the scanner's read). Block 0 is its
+     * header alone: java-tron answers `{}` to `gettransactioninfobyblocknum` there
+     * (`GetTransactionInfoByBlockNumServlet`, GreatVoyage-v4.8.2.2; Nile checked 2026-09-27),
+     * a malformed answer the scanner would retry for ever, and genesis holds only the chain's
+     * initial allocations, which are not reported.
+     */
+    blockWithTransactions(height: bigint, tags: TronCallTags): Promise<{
+        readonly header: TronBlockHeader;
+        readonly transactions: readonly TronTxJson[];
+        readonly infos: readonly TronTxInfo[];
+    } | null>;
+    chainParameters(tags: TronCallTags): Promise<ChainParameters>;
+    /** `{ exists: false }` for an account that was never activated. */
+    account(addressHex: string, tags: TronCallTags): Promise<{
+        readonly exists: boolean;
+        readonly balance: bigint;
+    }>;
+    resources(addressHex: string, tags: TronCallTags): Promise<TronResources>;
+    /**
+     * A constant (simulated) contract call. `no-contract` when the address holds no contract;
+     * `failed` when the call reverts or the VM fails; any other refusal is a retryable
+     * RPC_ERROR.
+     */
+    constantCall(ownerHex: string, contractHex: string, data: string, tags: TronCallTags): Promise<ConstantCall>;
+    /**
+     * Whether `addressHex` holds a contract (`/wallet/getcontract`): java-tron answers `{}`
+     * when the account or its contract does not exist (`Wallet.getContract`, GreatVoyage-v4.8.2.2
+     * `d5c3d1d1`), else the `SmartContract`. The structural check behind a constant call's
+     * "no contract" text before anyone caches it; an answer about another address is
+     * malformed.
+     */
+    contractExists(addressHex: string, tags: TronCallTags): Promise<boolean>;
+    /**
+     * `/wallet/broadcasthex`. java-tron answers refusals with HTTP 200, so the answer is read
+     * here; one that cannot be read is possibly sent (the node may hold the bytes).
+     */
+    broadcastHex(hexTx: string, tags: TronCallTags): Promise<BroadcastAnswer>;
+    /** An included transaction (`full`: any block; `solid`: a solidified one), or null. */
+    transaction(scope: 'full' | 'solid', id: string, tags: TronCallTags): Promise<TronTxJson | null>;
+    transactionInfo(scope: 'full' | 'solid', id: string, tags: TronCallTags): Promise<TronTxInfo | null>;
+    /** The transaction if the node holds `id` in its pending pool, else null. */
+    pending(id: string, tags: TronCallTags): Promise<TronTxJson | null>;
+    /** The node's JSON-RPC block read (transaction ids only), or null when it has none. */
+    rpcBlock(ref: bigint | string, tags: TronCallTags): Promise<RpcBlock | null>;
+}
+/**
+ * TronGrid `/v1` account history pages (indexer transport), confirmed entries only. Each
+ * transaction id is listed once per page: the TRC-20 stream lists a transaction once per
+ * transfer it made.
+ *
+ * Internal transactions are not listed. `search_internal=false` asks TronGrid for none,
+ * and an internal entry it mixes in anyway is skipped: TronGrid documents that entry shape
+ * (`internal_tx_id`, `tx_id`, `from_address`, `to_address`, `data`, `block_timestamp`; its
+ * OpenAPI schema at developers.tron.network/reference/get-transaction-info-by-account-address)
+ * and it has no `txID`, so one would make the whole page malformed. Only an entry without
+ * an id of its own that carries both documented ids is skipped. Read on 2026-09-27,
+ * `GET api.trongrid.io/v1/accounts/TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR/transactions?limit=20`
+ * (WTRX) gave only whole transactions (`txID`, `raw_data_hex`, …), each with the internal
+ * transfers nested in `internal_transactions[]` (`internal_tx_id`, `data`, `from_address`,
+ * `to_address`); five other accounts, internal-TRX recipients among them, looked the same
+ * with `search_internal` true or false. A TRX amount an account received only through a
+ * contract's internal transfer is therefore not in its history.
+ */
+export declare function historyPage(transport: Transport, address: string, kind: 'transactions' | 'trc20', options: {
+    readonly limit: number;
+    readonly fingerprint?: string;
+}, tags: TronCallTags): Promise<{
+    readonly ids: readonly string[];
+    readonly next?: string;
+}>;
+export {};