@getomnichain/omnichain 0.6.1 → 0.6.3

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/docs/utxo.md

@@ -14,8 +14,9 @@ rune / rare-sat filtering).
 
 - [utxo_chain.ts](../utxo/utxo_chain.ts) — `UtxoChain extends Chain`
 - [utxo_network_params.ts](../utxo/utxo_network_params.ts) — `UtxoNetworkParams`, SLIP-44 coin ids, derivation purposes, dust default, RBF sequence
-- [unsigned_utxo_transaction.ts](../utxo/unsigned_utxo_transaction.ts) — `UnsignedUtxoTransaction { psbtBase64, selectedInputs, feeSats, inputsToSign, … }`
-- [utxo.ts](../utxo/utxo.ts) — `UnspentTransactionOutput`, `RawTransactionView`, `FeeEstimate`, `AddressBalance`
+- [unsigned_utxo_transaction.ts](../utxo/unsigned_utxo_transaction.ts) — `UnsignedUtxoTransaction { psbtBase64, selectedInputs, feeSats, inputsToSign, … }`, `signWith`, `finalize`
+- [utxo.ts](../utxo/utxo.ts) — `UnspentTransactionOutput`, `RawTransactionView`, `FeeEstimate`, `AddressBalance`, `UtxoPsbtInput`, `UtxoPsbtOutput`, `UtxoSigner`, `FinalizedUtxoTransaction`
+- [raw_transaction.ts](../utxo/raw_transaction.ts) — `utxoFromRawTransaction` (reads one output of a raw transaction, no network call)
 - [script.ts](../utxo/script.ts) — `detectScriptType`, `buildOpReturnScript`, `scriptTypeForAddress`
 - [fee.ts](../utxo/fee.ts) — per-script-type vByte tables, fee math
 - [coin_selection.ts](../utxo/coin_selection.ts) — branch-and-bound + accumulator fallback over effective-value
@@ -184,11 +185,74 @@ this is intentional. Legacy inputs need `nonWitnessUtxo` for correctness;
 SegWit/Taproot inputs technically don't, but hardware wallets like Trezor
 and Phantom demand it. Populating both is the safe default.
 
+## Building from explicit inputs
+
+`assembleTransaction` builds a transaction from inputs you have already
+chosen, owned by any number of keys, with no coin selection and no
+automatic change. Each input carries its parent transaction:
+
+```ts
+const unsigned = btc.assembleTransaction({
+  inputs: [
+    { utxo: vaultUtxo, parentTxHex: vaultParentHex },
+    { utxo: operatorUtxo, parentTxHex: operatorParentHex },
+  ],
+  outputs: [
+    { kind: 'address', address: recipient, valueSats: 50_000 },
+    { kind: 'address', address: operatorAddress, valueSats: operatorChange },
+    { kind: 'opReturn', data: memoBytes },
+  ],
+  rbfEnabled: true,                     // optional, defaults to the chain's setting
+});
+```
+
+- Inputs and outputs keep the order given. If you want change, add it
+  as an `address` output.
+- `feeSats` is inputs minus outputs; `feeRateSatsPerVByte` is
+  `feeSats / estimatedVBytes`; `changeAddress` is `null`.
+- Every input is checked against its parent transaction: the txid,
+  the output's value and script, and that `ownerAddress` owns that
+  script. A mismatch throws, so the reported fee is the fee the chain
+  will charge.
+- Address outputs must be at or above the chain's dust value; at most
+  one OP_RETURN output of up to 80 bytes; outputs may not exceed inputs.
+
+`utxoFromRawTransaction(parentTxHex, vout, ownerAddress)` turns an output
+of a raw transaction you already hold into an `UnspentTransactionOutput`,
+without a network call.
+
 ## Signing
 
-The chain module never holds keys. You hand the PSBT to whatever signs
-it — a user's wallet, a hardware device, an external service. For
-testing or for protocol-controlled wallets that talk to Bitcoin Core:
+The chain module never holds keys. `signWith` takes a signer object — a
+33-byte compressed public key and a function that signs a 32-byte hash
+with a 64-byte compact ECDSA signature (what `ecpair` and
+`tiny-secp256k1` produce):
+
+```ts
+const { hex, txid, vsize } = unsigned
+  .signWith(vaultSigner)
+  .signWith(operatorSigner)
+  .finalize();
+await btc.broadcast(hex);
+```
+
+- `signWith` signs the P2WPKH and P2PKH inputs whose script belongs to
+  the signer's key and returns a new `UnsignedUtxoTransaction`; the
+  original is unchanged. Signing again with the same key is a no-op. It
+  throws if the key owns none of the inputs. Taproot, P2WSH and P2SH
+  inputs are never signed by it.
+- Before signing, and again in `finalize`, every input is checked against
+  its parent transaction: the parent must be present and be the one the
+  input spends, a declared amount and script must match the parent output,
+  and the real fee must equal `feeSats`. Otherwise nothing is signed.
+- `finalize` throws if any input is unsigned (naming the index),
+  verifies every signature (rejecting high-S ones), refuses a fee rate
+  of 5000 sat/vB or more, and returns the raw hex, txid and vsize.
+- Both work on transactions from `createTransferUnsignedTransaction` too.
+
+Alternatively, hand the PSBT to whatever signs it — a user's wallet, a
+hardware device, an external service. For testing or for
+protocol-controlled wallets that talk to Bitcoin Core:
 
 ```ts
 // Sign via Bitcoin Core's wallet (it has the keys for sender's address):
@@ -220,6 +284,17 @@ All five address types are supported per chain: P2PKH (`1…`), P2SH
 (`3…`), P2WPKH (`bc1q…` 42-char bech32), P2WSH (`bc1q…` 62-char bech32),
 P2TR (`bc1p…` bech32m).
 
+To derive the address of a public key on the chain's network:
+
+```ts
+btc.addressForPublicKey(publicKey);                       // P2WPKH (default)
+btc.addressForPublicKey(publicKey, UtxoScriptTypes.P2PKH); // P2PKH
+```
+
+Dogecoin has no segwit, so P2WPKH there throws `FeatureNotSupported`.
+`UtxoNetworkInfo` is the type of `chain.params.networkInfo`, for code that
+needs to name the network type without importing `bitcoinjs-lib`.
+
 ## Asset filtering (Bitcoin only)
 
 To avoid accidentally spending UTXOs that carry inscriptions, runes, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getomnichain/omnichain",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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",