@getomnichain/omnichain 0.6.2 → 0.7.0

package/docs/tron.md

@@ -36,7 +36,8 @@ const { transaction } = await TronMainnet.createTransferTransaction({
 - Native TRX builds a `TransferContract`. With `isFullBalance: true` the amount is reduced by 0.3 TRX (`DEFAULT_TRX_FEE_LIMIT_SUN`).
 - TRC-20 builds a `TriggerSmartContract` calling `transfer(address,uint256)` with a 15 TRX `fee_limit` (`DEFAULT_TRC20_TRANSFER_FEE_LIMIT_SUN`), or the `feeLimitSun` of an explicit `TronGasPricing`. `FeePriority` has no effect on Tron.
 - `memo` is stored hex-encoded in `raw_data.data`.
-- `raw_data` is built exactly like tronpy: current timestamp, 60 s expiration, TAPoS reference from the latest solid block (`wallet/getnodeinfo`). The txID and the account permission come from `wallet/getsignweight`.
+- `raw_data` is built like tronpy: current timestamp, 60 s expiration, TAPoS reference from the latest solid block (`wallet/getnodeinfo`). The txID is computed locally: `sha256` of the protobuf-encoded `raw_data` (`transaction.rawDataHex`). `wallet/getsignweight` is called only when `permissionId(...)` is set, and its txID must equal the local one. Building therefore costs one node call.
+- `TronTrx.buildTransaction(type, value)` builds `TransferContract`, `TriggerSmartContract` (any calldata and `call_value`), `FreezeBalanceV2Contract` and `DelegateResourceContract`, with `.memo()`, `.feeLimit()`, `.expiration()` and `.withOwner()`. These four are the contract types the local encoder supports; TRC-10 fields (`call_token_value`, `token_id`) must be 0.
 - `transaction.canonicalTransaction` parses the wire JSON into the 12-contract discriminated union from `helpers/transaction.py` (`parseTronCanonicalTransaction`).
 
 ## Signing and broadcasting
@@ -48,12 +49,14 @@ const response = await TronMainnet.broadcastSignedTransaction(signed);
 ```
 
 - Signatures are tronpy's: RFC 6979 recoverable `r || s || recid` over the txID, appended to the transaction's signature list (like tronpy, signing mutates the transaction). Messages use the TIP-191 `"\x19TRON Signed Message:\n"` keccak hash.
+- Signing recomputes the txID from `raw_data` and signs only that. A carried `txID` or `raw_data_hex` that does not match `raw_data`, or an unsupported contract type, is refused with `InvalidArgument` before the key is used.
+- Broadcasting re-checks the txID the same way before anything is sent, then requires the node's reply to name that txID (`RpcError` otherwise). A signed transaction can be stored with `signed.toJsonStr()` and re-broadcast later with `chain.broadcast(stored)` or `broadcastSignedTransaction(TronSignedTransaction.fromJson(stored))`: it is sent exactly as stored, with the same txID. A stored copy that was altered is refused with `InvalidArgument` and never reaches the node.
 - `broadcastSignedTransaction` never throws: node rejections such as `DUP_TRANSACTION_ERROR`, `SERVER_BUSY` or `BLOCK_UNSOLIDIFIED` come back as `broadcastError` with the txID kept. A reply without `txid` is Python's `KeyError('txid')`. The TS `Chain.broadcast` adapter accepts the signed JSON and throws. It throws `BroadcastRejected` only for the codes java-tron returns before accepting the transaction (`SIGERROR`, `CONTRACT_VALIDATE_ERROR`, `CONTRACT_EXE_ERROR`, `BANDWITH_ERROR`) and `TransactionTooLarge` for `TOO_BIG_TRANSACTION_ERROR`. Everything else, including `DUP_TRANSACTION_ERROR`, `SERVER_BUSY`, `OTHER_ERROR`, unknown codes and a reply without `txid`, is `RpcError`: the transaction may be on-chain, so check its status and re-broadcast the same signed bytes rather than re-signing, as Python's warning says. `TRANSACTION_EXPIRATION_ERROR` and `TAPOS_ERROR` are `RpcError` too: java-tron checks expiry before its duplicate check, so re-broadcasting a transaction that already landed returns them after the 60 s expiry.
 - `TronChain` constructs for any chain id (Nile, private networks) and never touches the network-type registry, as Python's constructor registers nothing.
-- `broadcastSignedTransaction` takes the node's `txid` like Python (`result.get("txid") or signed.tx_hash`). The `broadcast` adapter returns the signed txID (lowercase) and throws `RpcError` if the node answers a different one, compared case-insensitively.
+- `broadcastSignedTransaction` and the `broadcast` adapter return the signed txID (lowercase). A node reply naming a different txID, compared case-insensitively, is an `RpcError`.
 - Loading a TRC-20 contract checks the `getcontract` reply like tronpy's `AsyncContract`: a `bytecode` that is not hex and an `abi` that is not an object raise tronpy's texts before any other call.
 - A TronGrid reply that is valid JSON but not an object fails like Python's `payload.get` (`'str' object has no attribute 'get'`) as `RpcError`, without echoing the reply.
-- External signers sign `transaction.txId` and attach the signature with `transaction.transaction.setSignature([...])`.
+- External signers sign `transaction.txId` and attach the signature with `transaction.transaction.setSignature([...])`. `txId` is computed from `raw_data` and checked against any txID or `raw_data_hex` the payload carries, so a payload loaded from JSON cannot hand a signer someone else's txID: a mismatch throws `InvalidArgument`.
 - `TronWallet.handleTransactionPrerequisite` handles `TronApproveTransactionPrerequisite`. It reads the current allowance, skips if it is enough, and otherwise approves (25 TRX fee limit). For USDT-style tokens it first resets the allowance to 0 and waits three blocks; these are tokens in `ZERO_RESET_APPROVAL_TRC20_ADDRESSES` or prerequisites with `requiresZeroResetFirst`.
 
 ## Reading state
@@ -66,6 +69,17 @@ const response = await TronMainnet.broadcastSignedTransaction(signed);
   - plus the fee debited from the first contract's owner.
   
   Unknown TRC-20 tokens are resolved through `symbol()`/`decimals()`. `fees` is a `TronTransactionFees`, whose constructor enforces Python's rule `energyUsageTotal = energyUsage + originEnergyUsage + energyFee / getEnergyFee`.
+- Balance changes count only money that moved:
+  - an internal transaction counts as TRX only if it is not `rejected`, its `note` is `call` or `suicide` (staking and resource-delegation entries are skipped), and only its `callValueInfo` entries without a `tokenId` (TRC-10) are added up;
+  - the TRX a `TriggerSmartContract` sends as `call_value` is debited from the owner and credited to the contract;
+  - a `Transfer` log counts as TRC-20 only with exactly three topics and one 32-byte data word, so TRC-721 transfers are skipped.
+  These are the rules Clydner applies.
+- Successful and failed statuses also carry, from the same two node calls:
+  - `blockNumber`: the block that included the transaction;
+  - `signers`: the owner account of the transaction's contract (the authorizing account, not the keys that signed under a multi-signature permission); `[]` when the raw transaction cannot be fetched;
+  - `memoHex`: `raw_data.data` in lowercase hex, and `memo`: that hex decoded by `decodeTronMemo` (strict UTF-8, a leading byte-order mark dropped, `null` for no memo, invalid UTF-8 or bad hex). Clydner decodes memos the same way.
+  Pending and not-found statuses carry `null`, `[]`, `null`, `null`.
+- Confirmations are not on the status (`wait` and `confirmations` options stay refused). Compute them as `getChainTipHeight() − blockNumber + 1`. A poll loop should read the tip once per tick and reuse it for every transaction it checks in that tick, so confirmations cost one call per tick, not one per transaction.
 - `simulateTransaction` dry-runs `TriggerSmartContract` through `wallet/triggerconstantcontract` and reports `energyUsed`; other contract types throw `FeatureNotSupported` (Python's `NotImplementedError`). `supportsFullTransactionSimulation` is `false`.
 
 ## Differences from omnichain-py
@@ -79,8 +93,11 @@ const response = await TronMainnet.broadcastSignedTransaction(signed);
 | `private_key_hex` / `_private_key` are plain attributes | `#private` fields; `wallet.privateKeyHex` still returns the key | `JSON.stringify` and the default `util.inspect` never print the key or the TronGrid API key, and a non-JSON TronGrid reply never reaches an error text |
 | `is_base58check_address` raises `ValueError` on a bad checksum | Returns `false`; callers raise their own error | TS predicates do not throw |
 | `logger.warning` for non-NORMAL `FeePriority` | No logging | The TS SDK has no logger |
+| The txID comes from `wallet/getsignweight` and is signed as given | The txID is computed locally from the protobuf-encoded `raw_data`; a mismatching carried txID or `raw_data_hex` is refused before signing or broadcasting | A node or payload must not be able to get a signature over a different transaction. Python's fix is on RIN-328 |
+| Status counts rejected internal transactions, staking/delegation entries and TRC-10 `callValue` as TRX, and does not debit `call_value` | Only real TRX and TRC-20 moves are counted (see Reading state) | Deposits must not look larger than what arrived. Python's fix is on RIN-328 |
+| Status has no block number, signers or memo | `blockNumber`, `signers`, `memo`, `memoHex` | Read from data the status already fetches; no extra node calls |
 
-`TronClient` behaves like tronpy's httpx provider: it never follows redirects, it raises httpx's `raise_for_status` text on non-2xx responses, and its timeout restarts on every received chunk. Contract calls go through `tronAbiEncodeSingle` / `tronAbiDecodeSingle`, a port of tronpy's `trx_abi` (strict eth_abi decoding, Tron addresses inside arrays and tuples). `TronTransaction.sign` refuses the payloads tronpy's `AsyncTransaction.sign` refuses, with the same texts.
+`TronClient` behaves like tronpy's httpx provider: it never follows redirects, it raises httpx's `raise_for_status` text on non-2xx responses, and its timeout restarts on every received chunk. Contract calls go through `tronAbiEncodeSingle` / `tronAbiDecodeSingle`, a port of tronpy's `trx_abi` (strict eth_abi decoding, Tron addresses inside arrays and tuples). `TronTransaction.sign` keeps tronpy's texts for the refusals it shares with `AsyncTransaction.sign` (expired, permission list, signature list), and adds the local txID checks above.
 
 Hex input (keys, signatures, txIDs, node messages) is parsed exactly like Python's `bytes.fromhex`: ASCII whitespace is skipped, `0x` is not hex, and errors report only a position. The TS `verifyMessageSignature` adapter additionally accepts TronWeb's `0x`-prefixed signatures.
 
@@ -94,10 +111,3 @@ Hex input (keys, signatures, txIDs, node messages) is parsed exactly like Python
 ## Known limitation
 
 - TronGrid JSON integers above 2^53 lose precision in `JSON.parse` before they reach `BigInt`. Python's ints do not. Balances and amounts below 9,007,199,254 TRX (or 2^53 base units of a token) are exact.
-
-## Known issues shared with omnichain-py
-
-These are bugs in omnichain-py itself. They are kept for parity and tracked to be fixed in both SDKs:
-
-- RIN-317 — status counts rejected internal transactions and TRC-10 `callValue` as TRX, and does not debit TRX sent as `call_value`.
-- RIN-318 — the wallet signs the txID returned by the node (or found in a JSON payload) without recomputing it from `raw_data`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getomnichain/omnichain",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Multi-chain SDK for EVM, Solana, UTXO (BTC/LTC/DOGE/DASH/ZEC/BCH), Stellar, Tron, and TON. TypeScript parity port of omnichain-py.",
   "keywords": [
     "omnichain",
@@ -80,6 +80,7 @@
     "build:cjs": "tsc -p tsconfig.build.cjs.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js",
+    "test:live:ton": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js -c jest.live.config.mjs ton/test/live",
     "release": "bash scripts/release.sh",
     "rango:refresh": "node scripts/refresh-rango-fixture.mjs",
     "prepublishOnly": "npm test && npm run build"
@@ -88,6 +89,9 @@
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.0",
     "@stellar/stellar-sdk": "^15.1.0",
+    "@ton/core": "^0.63.1",
+    "@ton/crypto": "^3.3.0",
+    "@ton/ton": "^16.3.0",
     "axios": "^1.7.0",
     "bitcoinjs-lib": "^7.0.1",
     "bitcoinjs-message": "^2.2.0",