crypto-aio 0.0.3 → 0.1.0

package/dist/adapters/tron/errors.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyBroadcast = classifyBroadcast;
+exports.classifyOwnBroadcast = classifyOwnBroadcast;
+exports.txBytesOf = txBytesOf;
+const error_1 = require("../../core/errors/error");
+const bytes_1 = require("../../core/util/bytes");
+const protobuf_1 = require("./protobuf");
+const refused = (code, reason) => Object.freeze({ kind: 'refused', code, reason });
+const rejected = (reason) => Object.freeze({ kind: 'rejected', reason });
+const ACCEPTED = Object.freeze({ kind: 'accepted' });
+/** `Dup transaction.`, or `Transaction already exists.` from the id cache: never a failure. */
+const ALREADY_KNOWN = Object.freeze({ kind: 'already-known' });
+/** `Constant.PER_SIGN_LENGTH`: consensus (`TransactionCapsule.checkWeight`) refuses less. */
+const MIN_SIGNATURE_BYTES = 65;
+/** `Constant.TRANSACTION_MAX_BYTE_SIZE` (500 KiB). */
+const MAX_TX_BYTES = 512_000;
+/** `Constant.MAX_RESULT_SIZE_IN_TX` × 2, which the "with result" size check adds. */
+const RESULT_BYTES = 128;
+/**
+ * The signature and size rules measure the bytes as sent, while what lands is the
+ * txID with any signatures. A relayer may drop a signature, and java-tron reads only a
+ * signature's first 65 bytes (`checkWeight`), so it may trim padding too. So a claim holds
+ * only for bytes whose txID has no smaller valid form: one signature and, for the size, one
+ * of exactly 65 bytes.
+ */
+const oneSignature = (tx) => tx.signatures.length === 1;
+/** The size rules: java-tron measures the transaction without `ret`. */
+const oversize = (tx) => oneSignature(tx) && tx.signatures[0] === MIN_SIGNATURE_BYTES && tx.size > MAX_TX_BYTES;
+const PERMANENT = [
+    {
+        // Admission refuses sizes outside 65–68 (`SignUtils.isValidLength`), but consensus keeps
+        // `size < 65` (its own comment: longer historical signatures carry padding), so only a
+        // shorter signature is invalid everywhere.
+        code: 'SIGERROR',
+        text: /^Validate signature error: Signature size is (0|[1-9]\d{0,9})$/,
+        shows: (size) => size < MIN_SIGNATURE_BYTES,
+        holds: (tx) => oneSignature(tx) && tx.signatures[0] < MIN_SIGNATURE_BYTES,
+        result: rejected('malformed signature'),
+    },
+    {
+        // `Wallet.broadcastTransaction`: no contract at all (TransferActuator's use of the same
+        // text needs a missing parameter, which a parsed transaction never has).
+        code: 'CONTRACT_VALIDATE_ERROR',
+        text: /^Contract validate error : No contract!$/,
+        holds: (tx) => tx.contracts === 0,
+        result: rejected('no contract'),
+    },
+    {
+        code: 'CONTRACT_VALIDATE_ERROR',
+        text: /^Contract validate error : Cannot transfer TRX to yourself\.$/,
+        holds: (tx) => tx.transfer !== undefined && tx.transfer.owner === tx.transfer.to,
+        result: rejected('transfer to self'),
+    },
+    {
+        code: 'CONTRACT_VALIDATE_ERROR',
+        text: /^Contract validate error : Amount must be greater than 0\.$/,
+        holds: (tx) => tx.transfer !== undefined && tx.transfer.amount <= 0n,
+        result: rejected('non-positive amount'),
+    },
+    {
+        // `Manager.validateCommon`, applied in blocks too: the whole transaction.
+        code: 'TOO_BIG_TRANSACTION_ERROR',
+        text: /^Too big transaction, TxId [0-9a-f]{64}, the size is (0|[1-9]\d{0,18}) bytes, maxTxSize 512000$/,
+        shows: (size) => size > MAX_TX_BYTES,
+        holds: oversize,
+        result: rejected('transaction too large'),
+    },
+    {
+        // The size without results + 128 bytes; in blocks only under
+        // `allowConsensusLogicOptimization`, so only a size the plain check also refuses.
+        code: 'TOO_BIG_TRANSACTION_ERROR',
+        text: /^Too big transaction with result, TxId [0-9a-f]{64}, the size is (0|[1-9]\d{0,18}) bytes, maxTxSize 512000$/,
+        shows: (size) => size - RESULT_BYTES > MAX_TX_BYTES,
+        holds: oversize,
+        result: rejected('transaction too large'),
+    },
+];
+/** Refinements of `CONTRACT_VALIDATE_ERROR`: all state-dependent, so all `refused`. */
+const CONTRACT_REFUSALS = [
+    // `BandwidthProcessor.consume` refuses a missing owner before any contract check.
+    [
+        /^Contract validate error : account \[T[1-9A-HJ-NP-Za-km-z]{33}\] does not exist$/,
+        refused('INSUFFICIENT_FUNDS', 'sender account not activated'),
+    ],
+    // TransferActuator's own wording, which `consume` pre-empts in v4.8.2.2.
+    [
+        /^Contract validate error : Validate TransferContract error, no OwnerAccount\.$/,
+        refused('INSUFFICIENT_FUNDS', 'sender account not activated'),
+    ],
+    // TransferActuator (the amount) and `MUtil.transfer` (a call value).
+    [
+        /^Contract validate error : Validate (?:TransferContract|InternalTransfer) error, balance is not sufficient\.$/,
+        refused('INSUFFICIENT_FUNDS', 'insufficient balance'),
+    ],
+];
+/** The refusals java-tron answers before it pools the transaction, by code. */
+const REFUSED = new Map([
+    ['SIGERROR', refused('TX_REFUSED', 'signature not accepted for this account')],
+    ['CONTRACT_VALIDATE_ERROR', refused('TX_REFUSED', 'contract validation failed')],
+    ['CONTRACT_EXE_ERROR', refused('TX_REFUSED', 'contract execution failed')],
+    [
+        'BANDWITH_ERROR',
+        refused('INSUFFICIENT_FUNDS', 'insufficient bandwidth or balance for fees'),
+    ],
+    ['TAPOS_ERROR', refused('TX_REFUSED', 'reference block not on the canonical chain')],
+    ['TOO_BIG_TRANSACTION_ERROR', refused('TX_REFUSED', 'transaction refused')],
+    ['TRANSACTION_EXPIRATION_ERROR', refused('TX_EXPIRED', 'transaction expired')],
+]);
+const NODE_LOCAL = new Set([
+    'SERVER_BUSY',
+    'NO_CONNECTION',
+    'NOT_ENOUGH_EFFECTIVE_CONNECTION',
+    'BLOCK_UNSOLIDIFIED',
+]);
+function permanent(code, message) {
+    for (const rule of PERMANENT) {
+        if (rule.code !== code)
+            continue;
+        const match = rule.text.exec(message);
+        if (match === null)
+            continue;
+        if (rule.shows && !rule.shows(Number(match[1])))
+            return undefined;
+        return rule;
+    }
+    return undefined;
+}
+/** The node's answer at its word, with the rule when it claims a definitive rejection. */
+function classified(answer) {
+    if (answer.accepted)
+        return { result: ACCEPTED };
+    const { code = '', message = '' } = answer;
+    if (code === 'DUP_TRANSACTION_ERROR')
+        return { result: ALREADY_KNOWN };
+    const refusal = REFUSED.get(code);
+    if (refusal === undefined) {
+        throw new error_1.ProviderError('PROVIDER_UNAVAILABLE', NODE_LOCAL.has(code)
+            ? // "P2P broadcast failed." comes after java-tron pooled the transaction.
+                'the node could not relay the transaction; it may have been sent'
+            : 'the node answered the broadcast without a known refusal; it may have been sent', { ambiguous: true });
+    }
+    const rule = permanent(code, message);
+    if (rule)
+        return { result: rule.result, rule };
+    if (code === 'CONTRACT_VALIDATE_ERROR') {
+        for (const [text, result] of CONTRACT_REFUSALS) {
+            if (text.test(message))
+                return { result };
+        }
+    }
+    return { result: refusal };
+}
+/** The node's answer at its word (see `classifyOwnBroadcast` for our own broadcasts). */
+function classifyBroadcast(answer) {
+    return classified(answer).result;
+}
+/** A rejection this driver cannot confirm for the bytes it sent: observed, never terminal. */
+const UNCONFIRMED = refused('TX_REFUSED', 'the node claimed the transaction is invalid');
+/**
+ * The node's answer to bytes this driver sent, `sent` being those bytes read by
+ * `txBytesOf` (`undefined` when they do not read). A `rejected` stands only when its claimed
+ * reason holds for `sent`; otherwise the answer is `refused`. Every other answer is the
+ * node's, as `classifyBroadcast` reads it: acceptance, duplicates, state-dependent refusals
+ * (balance, a missing account, bandwidth, TaPoS, expiry, the fee limit) and possibly sent.
+ */
+function classifyOwnBroadcast(answer, sent) {
+    const { result, rule } = classified(answer);
+    if (rule === undefined)
+        return result;
+    return sent !== undefined && rule.holds(sent) ? result : UNCONFIRMED;
+}
+/** Bytes are read up to twice java-tron's transaction limit, and no further. */
+const MAX_READ_BYTES = 2 * MAX_TX_BYTES;
+const INT64_MAX = (1n << 63n) - 1n;
+const INT64_SPAN = 1n << 64n;
+const TRANSFER_URL = 'type.googleapis.com/protocol.TransferContract';
+/** `ContractType.TransferContract`. */
+const TRANSFER_TYPE = 1n;
+/** A field's bytes, or none: absent fields read as empty, as java-tron reads them. */
+const bytesField = (value) => (0, protobuf_1.bytesOf)(value) ?? new Uint8Array();
+/**
+ * The bytes a broadcast sent, as the rejection checks read them, SDK-free: `Transaction`
+ * (`raw_data` once, signatures, `ret` entries left out of the size), the contracts in
+ * `raw_data`, and a single TransferContract's fields. `undefined` for hex that does not read
+ * strictly, or is longer than `MAX_READ_BYTES`; no claim holds for it.
+ */
+function txBytesOf(hex) {
+    if (typeof hex !== 'string' || hex.length > 2 * MAX_READ_BYTES)
+        return undefined;
+    let bytes;
+    try {
+        bytes = (0, bytes_1.fromHex)(hex);
+    }
+    catch {
+        return undefined;
+    }
+    const outer = (0, protobuf_1.wireFields)(bytes, 'refuse');
+    if (!outer)
+        return undefined;
+    let raw;
+    let size = 0;
+    const signatures = [];
+    for (const { field, value, length } of outer) {
+        if (!(value instanceof Uint8Array))
+            return undefined;
+        if (field === 1 && raw === undefined)
+            raw = value;
+        else if (field === 2)
+            signatures.push(value.length);
+        else if (field !== 5)
+            return undefined;
+        // `ret` (field 5): java-tron clears it before it measures the transaction.
+        if (field !== 5)
+            size += length;
+    }
+    const fields = raw ? (0, protobuf_1.wireFields)(raw, 'refuse') : null;
+    if (!fields)
+        return undefined;
+    const contracts = fields.filter((f) => f.field === 11);
+    const read = { size, signatures, contracts: contracts.length };
+    const only = contracts.length === 1 ? contracts[0]?.value : undefined;
+    if (only === undefined)
+        return read;
+    if (!(only instanceof Uint8Array))
+        return undefined;
+    const contract = (0, protobuf_1.singular)(only, {
+        1: 'varint',
+        2: 'bytes',
+        3: 'bytes',
+        4: 'bytes',
+        5: 'varint',
+    });
+    if (!contract)
+        return undefined;
+    if (contract.get(1) !== TRANSFER_TYPE)
+        return read;
+    const any = (0, protobuf_1.singular)(bytesField(contract.get(2)), { 1: 'bytes', 2: 'bytes' });
+    if (!any)
+        return undefined;
+    // java-tron unpacks the parameter as the named type; any other type fails otherwise.
+    if ((0, bytes_1.toHex)(bytesField(any.get(1))) !== (0, bytes_1.toHex)((0, bytes_1.utf8ToBytes)(TRANSFER_URL)))
+        return read;
+    const transfer = (0, protobuf_1.singular)(bytesField(any.get(2)), {
+        1: 'bytes',
+        2: 'bytes',
+        3: 'varint',
+    });
+    if (!transfer)
+        return undefined;
+    const amount = transfer.get(3) ?? 0n;
+    return {
+        ...read,
+        transfer: {
+            owner: (0, bytes_1.toHex)(bytesField(transfer.get(1))),
+            to: (0, bytes_1.toHex)(bytesField(transfer.get(2))),
+            amount: amount > INT64_MAX ? amount - INT64_SPAN : amount,
+        },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/adapters/tron/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/adapters/tron/errors.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Broadcast classification, pure. java-tron answers\n * `/wallet/broadcasthex` with HTTP 200 and `{ result: false, code, message }`, so the\n * transport never sees these as errors. The codes, texts and their order are java-tron's\n * (`Wallet.broadcastTransaction`, `Manager.pushTransaction` and `processTransaction`,\n * checked against GreatVoyage-v4.8.2.2, `d5c3d1d1`).\n * - `rejected` only on definitive evidence: the refusal code plus an exact, anchored text\n *   that consensus also refuses for these bytes on every node at every time — a signature\n *   under 65 bytes, no contract, a transfer to self, a non-positive amount, or a size over\n *   the constant 512,000-byte limit (the signature and size rules only for bytes with one\n *   signature). Numbers in those texts must show the defect: a text that\n *   contradicts itself decides nothing.\n * - Refusal codes java-tron gives before it pools the transaction are `refused`, the\n *   default for any text: account state, permissions, chain parameters and node policy\n *   can change.\n * - Node-local codes (busy, not connected, not solidified, \"P2P broadcast failed.\", which\n *   java-tron returns after it pooled the transaction), `OTHER_ERROR` (its catch-all, which\n *   also covers a failure after pooling) and any empty or unknown code are thrown as a\n *   retryable `PROVIDER_UNAVAILABLE` marked `ambiguous`: possibly sent, even for a bare\n *   `Blockchain.broadcast` caller.\n * Nothing here decides from text alone: the code gates every result. Reasons are\n * fixed literals: no address, amount, transaction id or node text. Every pattern is\n * anchored and linear, whatever the message's length.\n *\n * A node's rejection is a claim. `classifyBroadcast` takes the node at\n * its word; `classifyOwnBroadcast`, which the broadcaster uses, keeps a `rejected` only when\n * the claimed reason holds for the bytes that were sent (`txBytesOf`, read with the SDK-free\n * reader the codec shares, `protobuf.ts`), and makes every other one `refused`, which\n * is not terminal. A terminal `rejected`\n * lets a caller pay again, so a lying endpoint that relayed the bytes, or keeps them to relay\n * later, would make that a second payment. Our builder refuses every byte-only defect before\n * signing, so a true rejection of our own bytes should not happen; a refusal costs liveness\n * only, and the expiry proof still ends the Operation.\n */\nimport type { BroadcastResult } from '../../core/driver/types';\nimport { ProviderError } from '../../core/errors/error';\nimport { fromHex, toHex, utf8ToBytes } from '../../core/util/bytes';\nimport type { BroadcastAnswer } from './http';\nimport { bytesOf, singular, wireFields, type WireValue } from './protobuf';\n\ntype RefusalCode = Extract<BroadcastResult, { kind: 'refused' }>['code'];\n\nconst refused = (code: RefusalCode, reason: string): BroadcastResult =>\n  Object.freeze({ kind: 'refused', code, reason });\nconst rejected = (reason: string): BroadcastResult =>\n  Object.freeze({ kind: 'rejected', reason });\n\nconst ACCEPTED: BroadcastResult = Object.freeze({ kind: 'accepted' });\n/** `Dup transaction.`, or `Transaction already exists.` from the id cache: never a failure. */\nconst ALREADY_KNOWN: BroadcastResult = Object.freeze({ kind: 'already-known' });\n\n/** `Constant.PER_SIGN_LENGTH`: consensus (`TransactionCapsule.checkWeight`) refuses less. */\nconst MIN_SIGNATURE_BYTES = 65;\n/** `Constant.TRANSACTION_MAX_BYTE_SIZE` (500 KiB). */\nconst MAX_TX_BYTES = 512_000;\n/** `Constant.MAX_RESULT_SIZE_IN_TX` × 2, which the \"with result\" size check adds. */\nconst RESULT_BYTES = 128;\n\n/**\n * Our signed transaction as java-tron's byte-only checks read it, from the hex\n * that was sent.\n */\nexport interface TronTxBytes {\n  /** The serialized `Transaction` without `ret`, which java-tron clears before measuring it. */\n  readonly size: number;\n  /** Each signature's length, in bytes. */\n  readonly signatures: readonly number[];\n  /** How many contracts `raw_data` holds (field 11). */\n  readonly contracts: number;\n  /**\n   * The one contract when it is a TransferContract: its addresses as hex and its amount as\n   * java-tron reads the `int64` (negative above 2^63 − 1; 0 when absent).\n   */\n  readonly transfer?: {\n    readonly owner: string;\n    readonly to: string;\n    readonly amount: bigint;\n  };\n}\n\ninterface Permanent {\n  readonly code: string;\n  readonly text: RegExp;\n  /** For a text with a number: whether the number shows the defect (else it decides nothing). */\n  readonly shows?: (value: number) => boolean;\n  /** Whether the claimed reason holds for the bytes that were sent. */\n  readonly holds: (tx: TronTxBytes) => boolean;\n  readonly result: BroadcastResult;\n}\n\n/**\n * The signature and size rules measure the bytes as sent, while what lands is the\n * txID with any signatures. A relayer may drop a signature, and java-tron reads only a\n * signature's first 65 bytes (`checkWeight`), so it may trim padding too. So a claim holds\n * only for bytes whose txID has no smaller valid form: one signature and, for the size, one\n * of exactly 65 bytes.\n */\nconst oneSignature = (tx: TronTxBytes): boolean => tx.signatures.length === 1;\n\n/** The size rules: java-tron measures the transaction without `ret`. */\nconst oversize = (tx: TronTxBytes): boolean =>\n  oneSignature(tx) && tx.signatures[0] === MIN_SIGNATURE_BYTES && tx.size > MAX_TX_BYTES;\n\nconst PERMANENT: readonly Permanent[] = [\n  {\n    // Admission refuses sizes outside 65–68 (`SignUtils.isValidLength`), but consensus keeps\n    // `size < 65` (its own comment: longer historical signatures carry padding), so only a\n    // shorter signature is invalid everywhere.\n    code: 'SIGERROR',\n    text: /^Validate signature error: Signature size is (0|[1-9]\\d{0,9})$/,\n    shows: (size) => size < MIN_SIGNATURE_BYTES,\n    holds: (tx) => oneSignature(tx) && (tx.signatures[0] as number) < MIN_SIGNATURE_BYTES,\n    result: rejected('malformed signature'),\n  },\n  {\n    // `Wallet.broadcastTransaction`: no contract at all (TransferActuator's use of the same\n    // text needs a missing parameter, which a parsed transaction never has).\n    code: 'CONTRACT_VALIDATE_ERROR',\n    text: /^Contract validate error : No contract!$/,\n    holds: (tx) => tx.contracts === 0,\n    result: rejected('no contract'),\n  },\n  {\n    code: 'CONTRACT_VALIDATE_ERROR',\n    text: /^Contract validate error : Cannot transfer TRX to yourself\\.$/,\n    holds: (tx) => tx.transfer !== undefined && tx.transfer.owner === tx.transfer.to,\n    result: rejected('transfer to self'),\n  },\n  {\n    code: 'CONTRACT_VALIDATE_ERROR',\n    text: /^Contract validate error : Amount must be greater than 0\\.$/,\n    holds: (tx) => tx.transfer !== undefined && tx.transfer.amount <= 0n,\n    result: rejected('non-positive amount'),\n  },\n  {\n    // `Manager.validateCommon`, applied in blocks too: the whole transaction.\n    code: 'TOO_BIG_TRANSACTION_ERROR',\n    text: /^Too big transaction, TxId [0-9a-f]{64}, the size is (0|[1-9]\\d{0,18}) bytes, maxTxSize 512000$/,\n    shows: (size) => size > MAX_TX_BYTES,\n    holds: oversize,\n    result: rejected('transaction too large'),\n  },\n  {\n    // The size without results + 128 bytes; in blocks only under\n    // `allowConsensusLogicOptimization`, so only a size the plain check also refuses.\n    code: 'TOO_BIG_TRANSACTION_ERROR',\n    text: /^Too big transaction with result, TxId [0-9a-f]{64}, the size is (0|[1-9]\\d{0,18}) bytes, maxTxSize 512000$/,\n    shows: (size) => size - RESULT_BYTES > MAX_TX_BYTES,\n    holds: oversize,\n    result: rejected('transaction too large'),\n  },\n];\n\n/** Refinements of `CONTRACT_VALIDATE_ERROR`: all state-dependent, so all `refused`. */\nconst CONTRACT_REFUSALS: readonly (readonly [RegExp, BroadcastResult])[] = [\n  // `BandwidthProcessor.consume` refuses a missing owner before any contract check.\n  [\n    /^Contract validate error : account \\[T[1-9A-HJ-NP-Za-km-z]{33}\\] does not exist$/,\n    refused('INSUFFICIENT_FUNDS', 'sender account not activated'),\n  ],\n  // TransferActuator's own wording, which `consume` pre-empts in v4.8.2.2.\n  [\n    /^Contract validate error : Validate TransferContract error, no OwnerAccount\\.$/,\n    refused('INSUFFICIENT_FUNDS', 'sender account not activated'),\n  ],\n  // TransferActuator (the amount) and `MUtil.transfer` (a call value).\n  [\n    /^Contract validate error : Validate (?:TransferContract|InternalTransfer) error, balance is not sufficient\\.$/,\n    refused('INSUFFICIENT_FUNDS', 'insufficient balance'),\n  ],\n];\n\n/** The refusals java-tron answers before it pools the transaction, by code. */\nconst REFUSED: ReadonlyMap<string, BroadcastResult> = new Map([\n  ['SIGERROR', refused('TX_REFUSED', 'signature not accepted for this account')],\n  ['CONTRACT_VALIDATE_ERROR', refused('TX_REFUSED', 'contract validation failed')],\n  ['CONTRACT_EXE_ERROR', refused('TX_REFUSED', 'contract execution failed')],\n  [\n    'BANDWITH_ERROR',\n    refused('INSUFFICIENT_FUNDS', 'insufficient bandwidth or balance for fees'),\n  ],\n  ['TAPOS_ERROR', refused('TX_REFUSED', 'reference block not on the canonical chain')],\n  ['TOO_BIG_TRANSACTION_ERROR', refused('TX_REFUSED', 'transaction refused')],\n  ['TRANSACTION_EXPIRATION_ERROR', refused('TX_EXPIRED', 'transaction expired')],\n]);\n\nconst NODE_LOCAL: ReadonlySet<string> = new Set([\n  'SERVER_BUSY',\n  'NO_CONNECTION',\n  'NOT_ENOUGH_EFFECTIVE_CONNECTION',\n  'BLOCK_UNSOLIDIFIED',\n]);\n\nfunction permanent(code: string, message: string): Permanent | undefined {\n  for (const rule of PERMANENT) {\n    if (rule.code !== code) continue;\n    const match = rule.text.exec(message);\n    if (match === null) continue;\n    if (rule.shows && !rule.shows(Number(match[1]))) return undefined;\n    return rule;\n  }\n  return undefined;\n}\n\n/** The node's answer at its word, with the rule when it claims a definitive rejection. */\nfunction classified(answer: BroadcastAnswer): {\n  readonly result: BroadcastResult;\n  readonly rule?: Permanent;\n} {\n  if (answer.accepted) return { result: ACCEPTED };\n  const { code = '', message = '' } = answer;\n  if (code === 'DUP_TRANSACTION_ERROR') return { result: ALREADY_KNOWN };\n  const refusal = REFUSED.get(code);\n  if (refusal === undefined) {\n    throw new ProviderError(\n      'PROVIDER_UNAVAILABLE',\n      NODE_LOCAL.has(code)\n        ? // \"P2P broadcast failed.\" comes after java-tron pooled the transaction.\n          'the node could not relay the transaction; it may have been sent'\n        : 'the node answered the broadcast without a known refusal; it may have been sent',\n      { ambiguous: true },\n    );\n  }\n  const rule = permanent(code, message);\n  if (rule) return { result: rule.result, rule };\n  if (code === 'CONTRACT_VALIDATE_ERROR') {\n    for (const [text, result] of CONTRACT_REFUSALS) {\n      if (text.test(message)) return { result };\n    }\n  }\n  return { result: refusal };\n}\n\n/** The node's answer at its word (see `classifyOwnBroadcast` for our own broadcasts). */\nexport function classifyBroadcast(answer: BroadcastAnswer): BroadcastResult {\n  return classified(answer).result;\n}\n\n/** A rejection this driver cannot confirm for the bytes it sent: observed, never terminal. */\nconst UNCONFIRMED: BroadcastResult = refused(\n  'TX_REFUSED',\n  'the node claimed the transaction is invalid',\n);\n\n/**\n * The node's answer to bytes this driver sent, `sent` being those bytes read by\n * `txBytesOf` (`undefined` when they do not read). A `rejected` stands only when its claimed\n * reason holds for `sent`; otherwise the answer is `refused`. Every other answer is the\n * node's, as `classifyBroadcast` reads it: acceptance, duplicates, state-dependent refusals\n * (balance, a missing account, bandwidth, TaPoS, expiry, the fee limit) and possibly sent.\n */\nexport function classifyOwnBroadcast(\n  answer: BroadcastAnswer,\n  sent: TronTxBytes | undefined,\n): BroadcastResult {\n  const { result, rule } = classified(answer);\n  if (rule === undefined) return result;\n  return sent !== undefined && rule.holds(sent) ? result : UNCONFIRMED;\n}\n\n/** Bytes are read up to twice java-tron's transaction limit, and no further. */\nconst MAX_READ_BYTES = 2 * MAX_TX_BYTES;\nconst INT64_MAX = (1n << 63n) - 1n;\nconst INT64_SPAN = 1n << 64n;\nconst TRANSFER_URL = 'type.googleapis.com/protocol.TransferContract';\n/** `ContractType.TransferContract`. */\nconst TRANSFER_TYPE = 1n;\n\n/** A field's bytes, or none: absent fields read as empty, as java-tron reads them. */\nconst bytesField = (value: WireValue | undefined): Uint8Array =>\n  bytesOf(value) ?? new Uint8Array();\n\n/**\n * The bytes a broadcast sent, as the rejection checks read them, SDK-free: `Transaction`\n * (`raw_data` once, signatures, `ret` entries left out of the size), the contracts in\n * `raw_data`, and a single TransferContract's fields. `undefined` for hex that does not read\n * strictly, or is longer than `MAX_READ_BYTES`; no claim holds for it.\n */\nexport function txBytesOf(hex: string): TronTxBytes | undefined {\n  if (typeof hex !== 'string' || hex.length > 2 * MAX_READ_BYTES) return undefined;\n  let bytes: Uint8Array;\n  try {\n    bytes = fromHex(hex);\n  } catch {\n    return undefined;\n  }\n  const outer = wireFields(bytes, 'refuse');\n  if (!outer) return undefined;\n  let raw: Uint8Array | undefined;\n  let size = 0;\n  const signatures: number[] = [];\n  for (const { field, value, length } of outer) {\n    if (!(value instanceof Uint8Array)) return undefined;\n    if (field === 1 && raw === undefined) raw = value;\n    else if (field === 2) signatures.push(value.length);\n    else if (field !== 5) return undefined;\n    // `ret` (field 5): java-tron clears it before it measures the transaction.\n    if (field !== 5) size += length;\n  }\n  const fields = raw ? wireFields(raw, 'refuse') : null;\n  if (!fields) return undefined;\n  const contracts = fields.filter((f) => f.field === 11);\n  const read = { size, signatures, contracts: contracts.length };\n  const only = contracts.length === 1 ? contracts[0]?.value : undefined;\n  if (only === undefined) return read;\n  if (!(only instanceof Uint8Array)) return undefined;\n  const contract = singular(only, {\n    1: 'varint',\n    2: 'bytes',\n    3: 'bytes',\n    4: 'bytes',\n    5: 'varint',\n  });\n  if (!contract) return undefined;\n  if (contract.get(1) !== TRANSFER_TYPE) return read;\n  const any = singular(bytesField(contract.get(2)), { 1: 'bytes', 2: 'bytes' });\n  if (!any) return undefined;\n  // java-tron unpacks the parameter as the named type; any other type fails otherwise.\n  if (toHex(bytesField(any.get(1))) !== toHex(utf8ToBytes(TRANSFER_URL))) return read;\n  const transfer = singular(bytesField(any.get(2)), {\n    1: 'bytes',\n    2: 'bytes',\n    3: 'varint',\n  });\n  if (!transfer) return undefined;\n  const amount = (transfer.get(3) as bigint | undefined) ?? 0n;\n  return {\n    ...read,\n    transfer: {\n      owner: toHex(bytesField(transfer.get(1))),\n      to: toHex(bytesField(transfer.get(2))),\n      amount: amount > INT64_MAX ? amount - INT64_SPAN : amount,\n    },\n  };\n}\n"]}

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

@@ -0,0 +1,49 @@
+import { type FeeEstimateDraft, type FeeOverride, type FeeSpeed } from '../../core/model/fee';
+import { type ChainParameters } from './http';
+import type { TronFeeOverride, TronResources } from './types';
+export interface TronFeeInput {
+    readonly fee: FeeSpeed | FeeOverride;
+    readonly params: ChainParameters;
+    /** The sender's resources now. */
+    readonly resources: TronResources;
+    /** Bytes of bandwidth: an upper bound of the signed size, plus 64. */
+    readonly bandwidth: bigint;
+    /** A TRX transfer to an account that does not exist yet. */
+    readonly activation: boolean;
+    readonly memo: boolean;
+    /** TRC-20 transfers: the simulated energy (`energy_used`, penalty included). */
+    readonly energy?: bigint;
+    /**
+     * Percent added to the simulated energy (dynamic energy can rise before inclusion): the
+     * network config's `energyMarginPercent`, an integer from 0 to 1,000.
+     */
+    readonly marginPercent: number;
+    /**
+     * The handle's fee-limit bound in sun (`TronNetworkConfig.maxFeeLimit`): from 1 to
+     * 2^53 − 1, the largest `fee_limit` the codec writes exactly.
+     */
+    readonly maxFeeLimit: bigint;
+}
+/** The fee-limit ceiling, and which bound sets it. */
+export interface FeeLimitCeiling {
+    readonly value: bigint;
+    /** `network`: `getMaxFeeLimit`, which no option can lift; `option`: the handle's bound. */
+    readonly bound: 'network' | 'option';
+}
+/**
+ * The largest fee limit a TRC-20 transfer may carry (one function for the estimate and
+ * its size bound): the network's `getMaxFeeLimit` (VMActuator refuses more) and the
+ * handle's `maxFeeLimit`. The node reports its maximum, as it reports the energy price and the
+ * simulated energy, so only the handle's bound is the operator's own. That bound is at most
+ * 2^53 − 1, so the ceiling is always encodable; on a tie the network is named, since raising
+ * the option would not help.
+ */
+export declare function feeLimitCeiling(params: Pick<ChainParameters, 'maxFeeLimit'>, maxFeeLimit: bigint): FeeLimitCeiling;
+/**
+ * A validated `{ feeLimit }` override, or `undefined` for a speed. Anything else, including
+ * a string that is not a speed or an override with another key, is `INVALID_INTENT`.
+ */
+export declare function feeOverrideOf(fee: FeeSpeed | FeeOverride): TronFeeOverride | undefined;
+export declare function tronFee(input: TronFeeInput): FeeEstimateDraft;
+/** Sum of every charge (all in TRX). */
+export declare const feeSun: (fee: FeeEstimateDraft) => bigint;

package/dist/adapters/tron/fees.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.feeSun = void 0;
+exports.feeLimitCeiling = feeLimitCeiling;
+exports.feeOverrideOf = feeOverrideOf;
+exports.tronFee = tronFee;
+/**
+ * The `tron` fee kind, pure: bandwidth, energy, account creation and the memo
+ * fee, from the chain's own parameters and the sender's resources. Every charge is in TRX
+ * (bigint sun, never a `Number`) and may be 0 (staked or free resources). The rules are
+ * java-tron's (checked against GreatVoyage-v4.8.2.2, `d5c3d1d1`):
+ * - bandwidth (`BandwidthProcessor.consume`): the signed size + 64 bytes, from staked
+ *   bandwidth, else free bandwidth, else burned at `getTransactionFee` per byte; a transfer
+ *   that creates the recipient's account uses staked bandwidth ×
+ *   `getCreateNewAccountBandwidthRate`, else burns `getCreateAccountFee`, and pays
+ *   `getCreateNewAccountFeeInSystemContract` on top (`TransferActuator`); it never uses
+ *   free bandwidth;
+ * - energy (`VMActuator.getAccountEnergyLimitWithFixRatio`): `fee_limit / getEnergyFee`
+ *   caps the call's energy, staked energy included, so the fee limit covers the whole
+ *   simulated energy plus a margin; only the part staked energy does not cover is burned;
+ * - a memo pays `getMemoFee` (`Manager.consumeMemoFee`).
+ */
+const error_1 = require("../../core/errors/error");
+const fee_1 = require("../../core/model/fee");
+const http_1 = require("./http");
+const network_1 = require("./network");
+function invalid(message) {
+    return new error_1.ValidationError('INVALID_INTENT', message);
+}
+/**
+ * The largest fee limit a TRC-20 transfer may carry (one function for the estimate and
+ * its size bound): the network's `getMaxFeeLimit` (VMActuator refuses more) and the
+ * handle's `maxFeeLimit`. The node reports its maximum, as it reports the energy price and the
+ * simulated energy, so only the handle's bound is the operator's own. That bound is at most
+ * 2^53 − 1, so the ceiling is always encodable; on a tie the network is named, since raising
+ * the option would not help.
+ */
+function feeLimitCeiling(params, maxFeeLimit) {
+    if (typeof maxFeeLimit !== 'bigint' ||
+        maxFeeLimit < 1n ||
+        maxFeeLimit > network_1.MAX_ENCODABLE_FEE_LIMIT) {
+        // The network config bounds it; anything else is a driver bug, never the caller's intent.
+        throw new error_1.ConfigError('CONFIG_INVALID', 'maxFeeLimit must be a bigint of sun from 1 to 2^53 − 1');
+    }
+    return params.maxFeeLimit <= maxFeeLimit
+        ? { value: params.maxFeeLimit, bound: 'network' }
+        : { value: maxFeeLimit, bound: 'option' };
+}
+/**
+ * What exceeds the ceiling, named after the bound that sets it. A need above the handle's
+ * bound carries it and the need (decimal strings), so the caller sees what to allow.
+ */
+function aboveCeiling(ceiling, need) {
+    if (ceiling.bound === 'network') {
+        return invalid(need !== undefined
+            ? "the transfer needs more energy than the network's maximum fee limit"
+            : "feeLimit is above the network's maximum fee limit");
+    }
+    if (need === undefined) {
+        return invalid('feeLimit is above maxFeeLimit, the Tron handle option that bounds it (in sun)');
+    }
+    return new error_1.ValidationError('INVALID_INTENT', 'the transfer needs more energy than maxFeeLimit allows (a Tron handle option, in sun)', { details: { required: need.toString(), maxFeeLimit: ceiling.value.toString() } });
+}
+/**
+ * A validated `{ feeLimit }` override, or `undefined` for a speed. Anything else, including
+ * a string that is not a speed or an override with another key, is `INVALID_INTENT`.
+ */
+function feeOverrideOf(fee) {
+    if ((0, fee_1.isFeeSpeed)(fee))
+        return undefined;
+    const shape = () => invalid('a Tron fee is a speed or { feeLimit: bigint } (sun, positive)');
+    if (fee === null || typeof fee !== 'object' || Array.isArray(fee))
+        throw shape();
+    const keys = Object.keys(fee);
+    const { feeLimit } = fee;
+    if (keys.length !== 1 || typeof feeLimit !== 'bigint' || feeLimit <= 0n) {
+        throw shape();
+    }
+    return { feeLimit };
+}
+const ceilDiv = (a, b) => (a + b - 1n) / b;
+const min = (a, b) => (a < b ? a : b);
+function tronFee(input) {
+    const { params, resources, bandwidth, marginPercent } = input;
+    if (!Number.isSafeInteger(marginPercent) || marginPercent < 0) {
+        // The network config bounds it (0–1,000); a fraction would throw a RangeError below.
+        throw new error_1.ConfigError('CONFIG_INVALID', 'energyMarginPercent must be a non-negative integer');
+    }
+    // Every transaction consumes bandwidth, and a TRC-20 call energy; a zero or negative
+    // one would give a fee limit of 0, which fails on chain (out of energy) and still pays.
+    // The bandwidth is the driver's own measure of the bytes it built (at least 133
+    // bytes, `bandwidthOf`), so a non-positive one is a driver bug: an internal, non-retryable
+    // CryptoAioError that fails the transfer before signing, never a foreign error.
+    // The energy is the node's simulation, so a non-positive one is a malformed answer
+    // (retryable).
+    if (bandwidth <= 0n) {
+        throw invalid('cannot estimate a Tron fee: the measured bandwidth is not positive');
+    }
+    if (input.energy !== undefined && input.energy <= 0n)
+        throw (0, http_1.malformed)('energy used');
+    const override = feeOverrideOf(input.fee);
+    const charges = [];
+    const charge = (label, amount) => charges.push({ asset: 'native', amount, label });
+    let bandwidthFee;
+    if (input.activation) {
+        const cost = bandwidth * params.createNewAccountBandwidthRate;
+        bandwidthFee = resources.stakedBandwidth >= cost ? 0n : params.createAccountFee;
+    }
+    else if (resources.stakedBandwidth >= bandwidth ||
+        resources.freeBandwidth >= bandwidth) {
+        bandwidthFee = 0n;
+    }
+    else {
+        bandwidthFee = bandwidth * params.transactionFee;
+    }
+    charge('bandwidth', bandwidthFee);
+    let energyDetails = {};
+    if (input.energy !== undefined) {
+        const need = ceilDiv(input.energy * BigInt(100 + marginPercent), 100n);
+        // Fee limit = min(estimate × margin, network maximum, maxFeeLimit). The ceiling
+        // caps the margin, never the simulated energy itself: a fee limit below that fails on
+        // chain (out of energy) and still pays, so a need above the ceiling is refused before
+        // anything is signed.
+        const ceiling = feeLimitCeiling(params, input.maxFeeLimit);
+        const cost = input.energy * params.energyFee;
+        if (cost > ceiling.value)
+            throw aboveCeiling(ceiling, cost);
+        const estimate = min(need * params.energyFee, ceiling.value);
+        let feeLimit = estimate;
+        if (override) {
+            if (override.feeLimit < estimate) {
+                throw invalid('feeLimit is below the estimated energy cost; the transaction would fail on chain and still pay');
+            }
+            if (override.feeLimit > ceiling.value)
+                throw aboveCeiling(ceiling);
+            feeLimit = override.feeLimit;
+        }
+        const covered = resources.energy * params.energyFee;
+        charge('energy', feeLimit > covered ? feeLimit - covered : 0n);
+        energyDetails = { energy: need, energyPrice: params.energyFee, feeLimit };
+    }
+    else if (override) {
+        throw invalid('a Tron fee override applies to TRC-20 transfers only');
+    }
+    if (input.activation)
+        charge('activation', params.createNewAccountFeeInSystemContract);
+    if (input.memo)
+        charge('memo', params.memoFee);
+    const details = {
+        bandwidth,
+        bandwidthPrice: params.transactionFee,
+        ...energyDetails,
+        activation: input.activation,
+    };
+    return {
+        kind: 'tron',
+        speed: override ? 'custom' : input.fee,
+        charges,
+        bound: 'upper',
+        details: { ...details },
+    };
+}
+/** Sum of every charge (all in TRX). */
+const feeSun = (fee) => fee.charges.reduce((sum, c) => sum + c.amount, 0n);
+exports.feeSun = feeSun;
+//# sourceMappingURL=fees.js.map

package/dist/adapters/tron/fees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fees.js","sourceRoot":"","sources":["../../../src/adapters/tron/fees.ts"],"names":[],"mappings":";;;AAuEA,0CAkBC;AA8BD,sCAWC;AAKD,0BAkFC;AAzND;;;;;;;;;;;;;;;GAeG;AACH,mDAAuE;AACvE,8CAM8B;AAC9B,iCAAyD;AACzD,uCAAoD;AAkCpD,SAAS,OAAO,CAAC,OAAe;IAC9B,OAAO,IAAI,uBAAe,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,eAAe,CAC7B,MAA4C,EAC5C,WAAmB;IAEnB,IACE,OAAO,WAAW,KAAK,QAAQ;QAC/B,WAAW,GAAG,EAAE;QAChB,WAAW,GAAG,iCAAuB,EACrC,CAAC;QACD,0FAA0F;QAC1F,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,wDAAwD,CACzD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,IAAI,WAAW;QACtC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE;QACjD,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,OAAwB,EAAE,IAAa;IAC3D,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,OAAO,CACZ,IAAI,KAAK,SAAS;YAChB,CAAC,CAAC,qEAAqE;YACvE,CAAC,CAAC,mDAAmD,CACxD,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,OAAO,CACZ,+EAA+E,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,uBAAe,CACxB,gBAAgB,EAChB,uFAAuF,EACvF,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,CAClF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,GAA2B;IACvD,IAAI,IAAA,gBAAU,EAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACtC,MAAM,KAAK,GAAG,GAAoB,EAAE,CAClC,OAAO,CAAC,+DAA+D,CAAC,CAAC;IAC3E,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,MAAM,KAAK,EAAE,CAAC;IACjF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,EAAE,QAAQ,EAAE,GAAG,GAA6B,CAAC;IACnD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QACxE,MAAM,KAAK,EAAE,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;AACnE,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D,SAAgB,OAAO,CAAC,KAAmB;IACzC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QAC9D,qFAAqF;QACrF,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,oDAAoD,CACrD,CAAC;IACJ,CAAC;IACD,qFAAqF;IACrF,wFAAwF;IACxF,gFAAgF;IAChF,2FAA2F;IAC3F,gFAAgF;IAChF,mFAAmF;IACnF,eAAe;IACf,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;QACpB,MAAM,OAAO,CAAC,oEAAoE,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE;QAAE,MAAM,IAAA,gBAAS,EAAC,aAAa,CAAC,CAAC;IACrF,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,MAAc,EAAE,EAAE,CAC/C,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAEnD,IAAI,YAAoB,CAAC;IACzB,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,6BAA6B,CAAC;QAC9D,YAAY,GAAG,SAAS,CAAC,eAAe,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC;IAClF,CAAC;SAAM,IACL,SAAS,CAAC,eAAe,IAAI,SAAS;QACtC,SAAS,CAAC,aAAa,IAAI,SAAS,EACpC,CAAC;QACD,YAAY,GAAG,EAAE,CAAC;IACpB,CAAC;SAAM,CAAC;QACN,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC;IACnD,CAAC;IACD,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAElC,IAAI,aAAa,GAAgE,EAAE,CAAC;IACpF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,GAAG,aAAa,CAAC,EAAE,IAAI,CAAC,CAAC;QACvE,gFAAgF;QAChF,sFAAsF;QACtF,sFAAsF;QACtF,sBAAsB;QACtB,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;QAC7C,IAAI,IAAI,GAAG,OAAO,CAAC,KAAK;YAAE,MAAM,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7D,IAAI,QAAQ,GAAG,QAAQ,CAAC;QACxB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,QAAQ,CAAC,QAAQ,GAAG,QAAQ,EAAE,CAAC;gBACjC,MAAM,OAAO,CACX,gGAAgG,CACjG,CAAC;YACJ,CAAC;YACD,IAAI,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAAC,KAAK;gBAAE,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;YACnE,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAC/B,CAAC;QACD,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;QACpD,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/D,aAAa,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAC;IAC5E,CAAC;SAAM,IAAI,QAAQ,EAAE,CAAC;QACpB,MAAM,OAAO,CAAC,sDAAsD,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,KAAK,CAAC,UAAU;QAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,mCAAmC,CAAC,CAAC;IACvF,IAAI,KAAK,CAAC,IAAI;QAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAE/C,MAAM,OAAO,GAAmB;QAC9B,SAAS;QACT,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,GAAG,aAAa;QAChB,UAAU,EAAE,KAAK,CAAC,UAAU;KAC7B,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAE,KAAK,CAAC,GAAgB;QACpD,OAAO;QACP,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE;KACxB,CAAC;AACJ,CAAC;AAED,wCAAwC;AACjC,MAAM,MAAM,GAAG,CAAC,GAAqB,EAAU,EAAE,CACtD,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AADxC,QAAA,MAAM,UACkC","sourcesContent":["/**\n * The `tron` fee kind, pure: bandwidth, energy, account creation and the memo\n * fee, from the chain's own parameters and the sender's resources. Every charge is in TRX\n * (bigint sun, never a `Number`) and may be 0 (staked or free resources). The rules are\n * java-tron's (checked against GreatVoyage-v4.8.2.2, `d5c3d1d1`):\n * - bandwidth (`BandwidthProcessor.consume`): the signed size + 64 bytes, from staked\n *   bandwidth, else free bandwidth, else burned at `getTransactionFee` per byte; a transfer\n *   that creates the recipient's account uses staked bandwidth ×\n *   `getCreateNewAccountBandwidthRate`, else burns `getCreateAccountFee`, and pays\n *   `getCreateNewAccountFeeInSystemContract` on top (`TransferActuator`); it never uses\n *   free bandwidth;\n * - energy (`VMActuator.getAccountEnergyLimitWithFixRatio`): `fee_limit / getEnergyFee`\n *   caps the call's energy, staked energy included, so the fee limit covers the whole\n *   simulated energy plus a margin; only the part staked energy does not cover is burned;\n * - a memo pays `getMemoFee` (`Manager.consumeMemoFee`).\n */\nimport { ConfigError, ValidationError } from '../../core/errors/error';\nimport {\n  isFeeSpeed,\n  type FeeChargeDraft,\n  type FeeEstimateDraft,\n  type FeeOverride,\n  type FeeSpeed,\n} from '../../core/model/fee';\nimport { malformed, type ChainParameters } from './http';\nimport { MAX_ENCODABLE_FEE_LIMIT } from './network';\nimport type { TronFeeDetails, TronFeeOverride, TronResources } from './types';\n\nexport interface TronFeeInput {\n  readonly fee: FeeSpeed | FeeOverride;\n  readonly params: ChainParameters;\n  /** The sender's resources now. */\n  readonly resources: TronResources;\n  /** Bytes of bandwidth: an upper bound of the signed size, plus 64. */\n  readonly bandwidth: bigint;\n  /** A TRX transfer to an account that does not exist yet. */\n  readonly activation: boolean;\n  readonly memo: boolean;\n  /** TRC-20 transfers: the simulated energy (`energy_used`, penalty included). */\n  readonly energy?: bigint;\n  /**\n   * Percent added to the simulated energy (dynamic energy can rise before inclusion): the\n   * network config's `energyMarginPercent`, an integer from 0 to 1,000.\n   */\n  readonly marginPercent: number;\n  /**\n   * The handle's fee-limit bound in sun (`TronNetworkConfig.maxFeeLimit`): from 1 to\n   * 2^53 − 1, the largest `fee_limit` the codec writes exactly.\n   */\n  readonly maxFeeLimit: bigint;\n}\n\n/** The fee-limit ceiling, and which bound sets it. */\nexport interface FeeLimitCeiling {\n  readonly value: bigint;\n  /** `network`: `getMaxFeeLimit`, which no option can lift; `option`: the handle's bound. */\n  readonly bound: 'network' | 'option';\n}\n\nfunction invalid(message: string): ValidationError {\n  return new ValidationError('INVALID_INTENT', message);\n}\n\n/**\n * The largest fee limit a TRC-20 transfer may carry (one function for the estimate and\n * its size bound): the network's `getMaxFeeLimit` (VMActuator refuses more) and the\n * handle's `maxFeeLimit`. The node reports its maximum, as it reports the energy price and the\n * simulated energy, so only the handle's bound is the operator's own. That bound is at most\n * 2^53 − 1, so the ceiling is always encodable; on a tie the network is named, since raising\n * the option would not help.\n */\nexport function feeLimitCeiling(\n  params: Pick<ChainParameters, 'maxFeeLimit'>,\n  maxFeeLimit: bigint,\n): FeeLimitCeiling {\n  if (\n    typeof maxFeeLimit !== 'bigint' ||\n    maxFeeLimit < 1n ||\n    maxFeeLimit > MAX_ENCODABLE_FEE_LIMIT\n  ) {\n    // The network config bounds it; anything else is a driver bug, never the caller's intent.\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      'maxFeeLimit must be a bigint of sun from 1 to 2^53 − 1',\n    );\n  }\n  return params.maxFeeLimit <= maxFeeLimit\n    ? { value: params.maxFeeLimit, bound: 'network' }\n    : { value: maxFeeLimit, bound: 'option' };\n}\n\n/**\n * What exceeds the ceiling, named after the bound that sets it. A need above the handle's\n * bound carries it and the need (decimal strings), so the caller sees what to allow.\n */\nfunction aboveCeiling(ceiling: FeeLimitCeiling, need?: bigint): ValidationError {\n  if (ceiling.bound === 'network') {\n    return invalid(\n      need !== undefined\n        ? \"the transfer needs more energy than the network's maximum fee limit\"\n        : \"feeLimit is above the network's maximum fee limit\",\n    );\n  }\n  if (need === undefined) {\n    return invalid(\n      'feeLimit is above maxFeeLimit, the Tron handle option that bounds it (in sun)',\n    );\n  }\n  return new ValidationError(\n    'INVALID_INTENT',\n    'the transfer needs more energy than maxFeeLimit allows (a Tron handle option, in sun)',\n    { details: { required: need.toString(), maxFeeLimit: ceiling.value.toString() } },\n  );\n}\n\n/**\n * A validated `{ feeLimit }` override, or `undefined` for a speed. Anything else, including\n * a string that is not a speed or an override with another key, is `INVALID_INTENT`.\n */\nexport function feeOverrideOf(fee: FeeSpeed | FeeOverride): TronFeeOverride | undefined {\n  if (isFeeSpeed(fee)) return undefined;\n  const shape = (): ValidationError =>\n    invalid('a Tron fee is a speed or { feeLimit: bigint } (sun, positive)');\n  if (fee === null || typeof fee !== 'object' || Array.isArray(fee)) throw shape();\n  const keys = Object.keys(fee);\n  const { feeLimit } = fee as { feeLimit?: unknown };\n  if (keys.length !== 1 || typeof feeLimit !== 'bigint' || feeLimit <= 0n) {\n    throw shape();\n  }\n  return { feeLimit };\n}\n\nconst ceilDiv = (a: bigint, b: bigint): bigint => (a + b - 1n) / b;\nconst min = (a: bigint, b: bigint): bigint => (a < b ? a : b);\n\nexport function tronFee(input: TronFeeInput): FeeEstimateDraft {\n  const { params, resources, bandwidth, marginPercent } = input;\n  if (!Number.isSafeInteger(marginPercent) || marginPercent < 0) {\n    // The network config bounds it (0–1,000); a fraction would throw a RangeError below.\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      'energyMarginPercent must be a non-negative integer',\n    );\n  }\n  // Every transaction consumes bandwidth, and a TRC-20 call energy; a zero or negative\n  // one would give a fee limit of 0, which fails on chain (out of energy) and still pays.\n  // The bandwidth is the driver's own measure of the bytes it built (at least 133\n  // bytes, `bandwidthOf`), so a non-positive one is a driver bug: an internal, non-retryable\n  // CryptoAioError that fails the transfer before signing, never a foreign error.\n  // The energy is the node's simulation, so a non-positive one is a malformed answer\n  // (retryable).\n  if (bandwidth <= 0n) {\n    throw invalid('cannot estimate a Tron fee: the measured bandwidth is not positive');\n  }\n  if (input.energy !== undefined && input.energy <= 0n) throw malformed('energy used');\n  const override = feeOverrideOf(input.fee);\n  const charges: FeeChargeDraft[] = [];\n  const charge = (label: string, amount: bigint) =>\n    charges.push({ asset: 'native', amount, label });\n\n  let bandwidthFee: bigint;\n  if (input.activation) {\n    const cost = bandwidth * params.createNewAccountBandwidthRate;\n    bandwidthFee = resources.stakedBandwidth >= cost ? 0n : params.createAccountFee;\n  } else if (\n    resources.stakedBandwidth >= bandwidth ||\n    resources.freeBandwidth >= bandwidth\n  ) {\n    bandwidthFee = 0n;\n  } else {\n    bandwidthFee = bandwidth * params.transactionFee;\n  }\n  charge('bandwidth', bandwidthFee);\n\n  let energyDetails: Pick<TronFeeDetails, 'energy' | 'energyPrice' | 'feeLimit'> = {};\n  if (input.energy !== undefined) {\n    const need = ceilDiv(input.energy * BigInt(100 + marginPercent), 100n);\n    // Fee limit = min(estimate × margin, network maximum, maxFeeLimit). The ceiling\n    // caps the margin, never the simulated energy itself: a fee limit below that fails on\n    // chain (out of energy) and still pays, so a need above the ceiling is refused before\n    // anything is signed.\n    const ceiling = feeLimitCeiling(params, input.maxFeeLimit);\n    const cost = input.energy * params.energyFee;\n    if (cost > ceiling.value) throw aboveCeiling(ceiling, cost);\n    const estimate = min(need * params.energyFee, ceiling.value);\n    let feeLimit = estimate;\n    if (override) {\n      if (override.feeLimit < estimate) {\n        throw invalid(\n          'feeLimit is below the estimated energy cost; the transaction would fail on chain and still pay',\n        );\n      }\n      if (override.feeLimit > ceiling.value) throw aboveCeiling(ceiling);\n      feeLimit = override.feeLimit;\n    }\n    const covered = resources.energy * params.energyFee;\n    charge('energy', feeLimit > covered ? feeLimit - covered : 0n);\n    energyDetails = { energy: need, energyPrice: params.energyFee, feeLimit };\n  } else if (override) {\n    throw invalid('a Tron fee override applies to TRC-20 transfers only');\n  }\n  if (input.activation) charge('activation', params.createNewAccountFeeInSystemContract);\n  if (input.memo) charge('memo', params.memoFee);\n\n  const details: TronFeeDetails = {\n    bandwidth,\n    bandwidthPrice: params.transactionFee,\n    ...energyDetails,\n    activation: input.activation,\n  };\n  return {\n    kind: 'tron',\n    speed: override ? 'custom' : (input.fee as FeeSpeed),\n    charges,\n    bound: 'upper',\n    details: { ...details },\n  };\n}\n\n/** Sum of every charge (all in TRX). */\nexport const feeSun = (fee: FeeEstimateDraft): bigint =>\n  fee.charges.reduce((sum, c) => sum + c.amount, 0n);\n"]}