Merge pull request #138 from hl-archive-node/feat/system-tx-sender-from-field

feat: use upstream `from` for system-tx sender

Author: sprites0

README.md

@@ -13,6 +13,20 @@ Ensure careful handling when indexing.
 
 To disable this behavior, add `--hl-node-compliant` to the CLI arguments-this will not show system transactions and their receipts, mimicking hl-node's output.
 
+### System transaction sender encoding
+
+System transactions arrive from hl-node unsigned; nanoreth fabricates a signature that encodes the real `msg.sender` into its `s` value. Sender recovery decodes it back:
+
+| `s` | recovered `msg.sender` |
+| --- | --- |
+| `1` | `0x2222...2222` (the HYPE system address) |
+| `0x10000000000000000000000000000000000000001` | `0x00...01` |
+| anything else | the low 20 bytes of `s` (e.g. spot-token `0x2000...00` senders) |
+
+The middle row is an escape: a real sender of `0x00...01` would otherwise encode to `s == 1` and collide with the HYPE sentinel, so it is lifted to `(1 << 160) | 1` (which still decodes back via the low 20 bytes).
+
+The RPC returns this recovered address as each transaction's `from`; together with the zero `gasPrice` and the table above, that lets you recognize system transactions. To confirm them authoritatively, use hl-node's [`eth_getSystemTxsByBlockHash` / `eth_getSystemTxsByBlockNumber`](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/hyperevm/json-rpc) methods, which return the system transactions originating from HyperCore, and source blocks only from a node you trust.
+
 ### Per-request compliance multiplexing
 
 If you need a single endpoint to serve both filtered and unfiltered responses, use `--hl-node-compliant-multiplexed`. This adds a middleware layer that reads the `?hl=` query parameter from each request:

src/node/primitives/transaction.rs

@@ -10,7 +10,7 @@ use alloy_consensus::{
 };
 use alloy_eips::Encodable2718;
 use alloy_network::TxSigner;
-use alloy_primitives::{Address, TxHash, U256, address};
+use alloy_primitives::{Address, TxHash, U256, address, uint};
 use alloy_rpc_types::{Transaction, TransactionInfo, TransactionRequest};
 use alloy_signer::Signature;
 use reth_codecs::alloy::transaction::{Envelope, FromTxCompact};
@@ -39,13 +39,37 @@ pub enum TransactionSigned {
     Default(InnerType),
 }
 
+/// The HYPE system address (sender of native HYPE transfer system txs), encoded as `s == 1`.
+/// <https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/hyperevm/hypercore-less-than-greater-than-hyperevm-transfers>
+const HYPE_SYSTEM_ADDRESS: Address = address!("2222222222222222222222222222222222222222");
+
+/// 0x00..01: its natural encoding `s == 1` would collide with [`HYPE_SYSTEM_ADDRESS`], so it is
+/// escaped to [`ADDRESS_ONE_S`].
+const ADDRESS_ONE: Address = address!("0000000000000000000000000000000000000001");
+
+/// The escaped `s` for [`ADDRESS_ONE`]: `(1 << 160) | 1`, one bit above the 20-byte address space.
+const ADDRESS_ONE_S: U256 = uint!(0x10000000000000000000000000000000000000001_U256);
+
+/// Decode a system tx's synthetic signature `s` into `msg.sender`; inverse of [`address_to_s`].
 fn s_to_address(s: U256) -> Address {
     if s == U256::ONE {
-        return address!("2222222222222222222222222222222222222222");
+        return HYPE_SYSTEM_ADDRESS;
+    }
+    if s == ADDRESS_ONE_S {
+        return ADDRESS_ONE;
+    }
+    Address::from_slice(&s.to_be_bytes::<32>()[12..])
+}
+
+/// Encode `msg.sender` into a system tx's synthetic signature `s`; inverse of [`s_to_address`].
+pub(crate) fn address_to_s(addr: Address) -> U256 {
+    if addr == HYPE_SYSTEM_ADDRESS {
+        return U256::ONE;
+    }
+    if addr == ADDRESS_ONE {
+        return ADDRESS_ONE_S;
     }
-    let mut buf = [0u8; 20];
-    buf[0..20].copy_from_slice(&s.to_be_bytes::<32>()[12..32]);
-    Address::from_slice(&buf)
+    U256::from_be_slice(addr.as_slice())
 }
 
 impl TxHashRef for TransactionSigned {

src/node/types/mod.rs

@@ -7,7 +7,7 @@ use alloy_primitives::{Address, B256, Bytes, Log};
 use alloy_rlp::{Decodable, Encodable, RlpDecodable, RlpEncodable};
 use bytes::BufMut;
 use reth_ethereum_primitives::EthereumReceipt;
-use reth_primitives_traits::InMemorySize;
+use reth_primitives_traits::{InMemorySize, SignerRecoverable};
 use serde::{Deserialize, Serialize};
 
 use crate::HlBlock;
@@ -118,9 +118,13 @@ impl BlockAndReceipts {
         let system_txs: Vec<SystemTx> = system_tx_list
             .into_iter()
             .zip(system_receipts)
-            .map(|(tx, receipt)| SystemTx {
-                tx: reth_compat::TransactionSigned::extract_transaction(tx),
-                receipt: Some(receipt.into()),
+            .map(|(tx, receipt)| {
+                let from = tx.recover_signer().ok();
+                SystemTx {
+                    tx: reth_compat::TransactionSigned::extract_transaction(tx),
+                    receipt: Some(receipt.into()),
+                    from,
+                }
             })
             .collect();
 
@@ -226,6 +230,8 @@ enum LegacyTxType {
 pub struct SystemTx {
     pub tx: reth_compat::Transaction,
     pub receipt: Option<LegacyReceipt>,
+    #[serde(default)]
+    pub from: Option<Address>,
 }
 
 impl SystemTx {

src/node/types/patch.rs

@@ -2,8 +2,9 @@
 use super::LegacyReceipt;
 use crate::chainspec::TESTNET_CHAIN_ID;
 use alloy_primitives::{Address, B256, U256, address, b256};
+use std::ops::Range;
 
-/// `keccak256("Transfer(address,address,uint256)")` — the ERC-20 `Transfer` topic.
+/// `keccak256("Transfer(address,address,uint256)")` - the ERC-20 `Transfer` topic.
 const ERC20_TRANSFER_TOPIC: B256 =
     b256!("ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef");
 
@@ -14,12 +15,14 @@ const ERC20_TRANSFER_TOPIC: B256 =
 /// once the true `msg.sender` is recovered from the receipt.
 const SENDER_RECOVERY_TOKEN: Address = address!("0x2b3370ee501b4a559b57d449569354196457d8ab");
 
-/// First testnet block at which the recovery applies.
-const SENDER_RECOVERY_FROM_BLOCK: u64 = 55231857;
+/// Half-open testnet block range in which the recovery applies: from the first affected block
+/// until upstream starts emitting `from`, which supersedes this log recovery (the next system tx,
+/// at `55432087`, carries it; none occur in between).
+const SENDER_RECOVERY_BLOCKS: Range<u64> = 55231857..55432000;
 
 /// Recover the real `msg.sender` of a token system transaction from its receipt,
-/// restricted to the minimal known-affected set (testnet, one token, at or after
-/// the first affected block). Returns `None` everywhere else so the caller falls
+/// restricted to the minimal known-affected set (testnet, one token,
+/// [`SENDER_RECOVERY_BLOCKS`]). Returns `None` everywhere else so the caller falls
 /// back to the legacy synthetic-sender (`to_s`) encoding.
 ///
 /// For an ERC-20 transfer the caller is observable as the `from` topic of the
@@ -31,7 +34,7 @@ pub(super) fn recover_testnet_system_tx_sender(
     receipt: Option<&LegacyReceipt>,
 ) -> Option<Address> {
     if chain_id != TESTNET_CHAIN_ID
-        || block_number < SENDER_RECOVERY_FROM_BLOCK
+        || !SENDER_RECOVERY_BLOCKS.contains(&block_number)
         || token != SENDER_RECOVERY_TOKEN
     {
         return None;
@@ -85,7 +88,7 @@ mod tests {
     fn recovers_sender_for_targeted_token() {
         let logs = vec![transfer_log(SENDER_RECOVERY_TOKEN, HOLDER_B, HOLDER_A)];
         assert_eq!(
-            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_FROM_BLOCK, SENDER_RECOVERY_TOKEN, logs),
+            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.start, SENDER_RECOVERY_TOKEN, logs),
             Some(HOLDER_B)
         );
     }
@@ -94,23 +97,32 @@ mod tests {
     fn declines_outside_the_minimal_set() {
         let log = || vec![transfer_log(SENDER_RECOVERY_TOKEN, HOLDER_B, HOLDER_A)];
         // wrong chain
-        assert_eq!(recover(999, SENDER_RECOVERY_FROM_BLOCK, SENDER_RECOVERY_TOKEN, log()), None);
+        assert_eq!(recover(999, SENDER_RECOVERY_BLOCKS.start, SENDER_RECOVERY_TOKEN, log()), None);
         // before the first affected block
         assert_eq!(
-            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_FROM_BLOCK - 1, SENDER_RECOVERY_TOKEN, log()),
+            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.start - 1, SENDER_RECOVERY_TOKEN, log()),
             None
         );
+        // at/after the upper bound, `from` supersedes log recovery
+        assert_eq!(
+            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.end, SENDER_RECOVERY_TOKEN, log()),
+            None
+        );
+        assert_eq!(
+            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.end - 1, SENDER_RECOVERY_TOKEN, log()),
+            Some(HOLDER_B)
+        );
         // a different (non-targeted) token, even though it emits a Transfer
         let other = vec![transfer_log(OTHER_TOKEN, HOLDER_B, HOLDER_A)];
-        assert_eq!(recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_FROM_BLOCK, OTHER_TOKEN, other), None);
+        assert_eq!(recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.start, OTHER_TOKEN, other), None);
     }
 
     #[test]
     fn ignores_unrelated_logs() {
         // Transfer emitted by some other contract (not the token `to`).
         let foreign = vec![transfer_log(OTHER_TOKEN, HOLDER_B, HOLDER_A)];
         assert_eq!(
-            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_FROM_BLOCK, SENDER_RECOVERY_TOKEN, foreign),
+            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.start, SENDER_RECOVERY_TOKEN, foreign),
             None
         );
         // Non-Transfer event (wrong topic0) from the token.
@@ -122,7 +134,7 @@ mod tests {
             ),
         };
         assert_eq!(
-            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_FROM_BLOCK, SENDER_RECOVERY_TOKEN, vec![
+            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.start, SENDER_RECOVERY_TOKEN, vec![
                 approval
             ]),
             None
@@ -134,7 +146,7 @@ mod tests {
         let one = address!("0000000000000000000000000000000000000001");
         let logs = vec![transfer_log(SENDER_RECOVERY_TOKEN, one, HOLDER_A)];
         assert_eq!(
-            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_FROM_BLOCK, SENDER_RECOVERY_TOKEN, logs),
+            recover(TESTNET_CHAIN_ID, SENDER_RECOVERY_BLOCKS.start, SENDER_RECOVERY_TOKEN, logs),
             None
         );
     }

src/node/types/reth_compat.rs

@@ -16,7 +16,7 @@ use super::patch::recover_testnet_system_tx_sender;
 use crate::{
     HlBlock, HlBlockBody, HlHeader,
     node::{
-        primitives::TransactionSigned as TxSigned,
+        primitives::{TransactionSigned as TxSigned, transaction::address_to_s},
         spot_meta::{SpotId, erc20_contract_to_spot_token},
         types::{LegacyReceipt, ReadPrecompileCalls, SystemTx},
     },
@@ -191,18 +191,18 @@ fn system_tx_to_reth_transaction(
     let TxKind::Call(to) = tx.to else {
         panic!("Unexpected contract creation");
     };
-    let s = if let Some(sender) = recover_testnet_system_tx_sender(
-        chain_id,
-        block_number,
-        to,
-        transaction.receipt.as_ref(),
-    ) {
-        // Encode the real `msg.sender` (recovered from the ERC-20 `Transfer` log) into
-        // `s`, so that `s_to_address(s)` recovers the actual holder. This lets each
-        // sender's nonces validate normally, removing the need to disable nonce checks
-        // for these system transactions.
-        U256::from_be_slice(sender.as_slice())
+    // System txs arrive unsigned; nanoreth fabricates the signature below, encoding `msg.sender`
+    // into `s` (via `address_to_s`) so `s_to_address(s)` recovers the holder and nonces validate.
+    let s = if let Some(sender) = transaction.from {
+        // Prefer the authoritative upstream `from`.
+        address_to_s(sender)
+    } else if let Some(sender) =
+        recover_testnet_system_tx_sender(chain_id, block_number, to, transaction.receipt.as_ref())
+    {
+        // Fall back to `super::patch` testnet log recovery.
+        address_to_s(sender)
     } else if tx.input.is_empty() {
+        // Native HYPE transfer: sender is the HYPE system address (0x2222…2222), encoded `s == 1`.
         U256::from(0x1)
     } else {
         loop {
@@ -326,6 +326,8 @@ mod tests {
                 input: Bytes::from_static(&[0xa9, 0x05, 0x9c, 0xbb]),
             }),
             receipt: Some(receipt),
+            // `from` path set explicitly per-test.
+            from: None,
         }
     }
 
@@ -342,4 +344,80 @@ mod tests {
         let signed2 = system_tx_to_reth_transaction(&tx2, TESTNET_CHAIN_ID, FROM_BLOCK);
         assert_eq!(signed2.recover_signer().unwrap(), HOLDER_A);
     }
+
+    #[test]
+    fn from_field_takes_precedence_over_log() {
+        // On disagreement, upstream `from` wins over the `Transfer` log.
+        let mut tx = system_tx(HOLDER_A, TOKEN, 3);
+        tx.from = Some(HOLDER_B);
+        let signed = system_tx_to_reth_transaction(&tx, TESTNET_CHAIN_ID, FROM_BLOCK);
+        assert_eq!(signed.recover_signer().unwrap(), HOLDER_B);
+    }
+
+    #[test]
+    fn from_db_round_trip_preserves_real_holder() {
+        // A `from`-bearing system tx past the log-recovery window survives the sync round trip
+        // (to_reth_block -> from_db -> to_reth_block) recovering the real holder, not a collision.
+        let mut tx = system_tx(HOLDER_A, TOKEN, 1);
+        tx.from = Some(HOLDER_B);
+        assert_eq!(round_trip_signer(tx), HOLDER_B);
+    }
+
+    #[test]
+    fn from_db_round_trip_preserves_hype_sender() {
+        // A native HYPE transfer (empty input, sender = HYPE system address -> `s == 1`) recovers
+        // to 0x2222…2222 and re-encodes back to `s == 1` across the round trip - no drift.
+        let receipt: LegacyReceipt = EthereumReceipt {
+            tx_type: TxType::Legacy,
+            success: true,
+            cumulative_gas_used: 0,
+            logs: vec![],
+        }
+        .into();
+        let tx = SystemTx {
+            tx: Transaction::Legacy(TxLegacy {
+                chain_id: Some(TESTNET_CHAIN_ID),
+                nonce: 0,
+                gas_price: 0,
+                gas_limit: 200_000,
+                to: TxKind::Call(TOKEN),
+                value: U256::ZERO,
+                input: Bytes::new(),
+            }),
+            receipt: Some(receipt),
+            from: None,
+        };
+        assert_eq!(round_trip_signer(tx), address!("2222222222222222222222222222222222222222"));
+    }
+
+    #[test]
+    fn degenerate_from_one_is_escaped_and_round_trips() {
+        // `from == 0x00..01` would collide with the `s == 1` sentinel; the escape lifts it above
+        // the address space so it recovers to 0x00..01 (not the 0x2222 sentinel) and round-trips.
+        let one = address!("0000000000000000000000000000000000000001");
+        let mut tx = system_tx(HOLDER_A, TOKEN, 1);
+        tx.from = Some(one);
+        let signed = system_tx_to_reth_transaction(&tx, TESTNET_CHAIN_ID, FROM_BLOCK);
+        assert_eq!(signed.recover_signer().unwrap(), one);
+        assert_eq!(round_trip_signer(tx), one);
+    }
+
+    /// Full sync round trip (to_reth_block -> from_db -> to_reth_block); returns the re-served
+    /// system tx's recovered signer, which must equal the original's.
+    fn round_trip_signer(tx: SystemTx) -> Address {
+        let sealed = SealedBlock {
+            header: SealedHeader {
+                hash: Default::default(),
+                header: Header { number: 56_000_000, ..Default::default() },
+            },
+            body: BlockBody { transactions: vec![], ommers: vec![], withdrawals: None },
+        };
+        let receipts = vec![tx.receipt.clone().unwrap().into()];
+        let block =
+            sealed.to_reth_block(Default::default(), None, vec![tx], vec![], TESTNET_CHAIN_ID);
+        let restored = crate::node::types::BlockAndReceipts::from_db(block, receipts);
+        assert_eq!(restored.system_txs.len(), 1);
+        let reserved = restored.to_reth_block(TESTNET_CHAIN_ID);
+        reserved.body.inner.transactions[0].recover_signer().unwrap()
+    }
 }