feat(tx): Add shielded outputs for amount and token privacy by msbrogli · Pull Request #1603 · HathorNetwork/hathor-core

msbrogli · 2026-02-24T21:17:23Z

Motivation

What was the motivation for the changes in this PR?

Acceptance Criteria

Include here all things that this PR should solve

Checklist

If you are requesting a merge into master, confirm this code is production-ready and can be included in future releases as soon as it gets merged

msbrogli · 2026-02-25T05:12:53Z

hathor/indexes/utxo_index.py

        # remove all inputs
        for tx_input in tx.inputs:
            spent_tx = tx.get_spent_tx(tx_input)
+            # CONS-018: skip shielded outputs — they are never in the UTXO index


This change is wrong. It should actually include the utxo to the index regardless of the output type. But it might need some change when querying and filtering by value/token.

msbrogli · 2026-02-25T05:13:26Z

hathor/indexes/utxo_index.py

        for tx_input in tx.inputs:
            spent_tx = tx.get_spent_tx(tx_input)
+            # CONS-018: skip shielded outputs — they are never in the UTXO index
+            if spent_tx.is_shielded_output(tx_input.index):


Same here. The index should work with shielded outputs.

msbrogli · 2026-02-25T05:14:14Z

hathor/nanocontracts/vertex_data.py

-    assert len(vertex2.outputs) > txin.index, 'invalid output index'
+    # CONS-024: return None for shielded output indices instead of crashing
+    if txin.index >= len(vertex2.outputs):
+        return None


Why not return the shielded output?

msbrogli · 2026-02-25T05:15:05Z

hathor/p2p/sync_v2/transaction_streaming_client.py

                nanocontracts=False,
                fee_tokens=False,
                opcodes_version=OpcodesVersion.V1,
+                shielded_transactions=True,


Should it be false?

msbrogli · 2026-02-25T05:16:35Z

hathor/transaction/headers/types.py

 class VertexHeaderId(Enum):
    NANO_HEADER = b'\x10'
    FEE_HEADER = b'\x11'
+    SHIELDED_OUTPUTS_HEADER = b'\x12'


Should headers be forced to be ordered according to the header id? This might prevent tx maleability.

msbrogli · 2026-02-25T05:27:24Z

hathor/transaction/scripts/execute.py

+    if txin.index < len(spent_tx.outputs):
+        output_script = spent_tx.outputs[txin.index].script
+    elif spent_tx.shielded_outputs:
+        shielded_idx = txin.index - len(spent_tx.outputs)
+        if shielded_idx >= len(spent_tx.shielded_outputs):
+            raise InvalidScriptError(f'input index {txin.index} out of range')
+        output_script = spent_tx.shielded_outputs[shielded_idx].script


Refactor to spent_tx.get_output(n) (or similar if you know a better name). Actually, maybe tx.outputs should be refactores to tx._outputs but that's a big task for this PR.

Why not use resolve_spent_output()?

msbrogli · 2026-02-25T05:29:05Z

hathor/transaction/scripts/opcode.py

-    contract_value = spent_tx.outputs[txin.index].value
+    # CONS-020: use resolve_spent_output for shielded-aware lookup
+    resolved = spent_tx.resolve_spent_output(txin.index)
+    if not hasattr(resolved, 'value'):


Why not use output.mode? We just have to add it to the TxOutput as Transparent mode.

msbrogli · 2026-02-25T05:30:40Z

hathor/transaction/exceptions.py

+
+
+class TrivialCommitmentError(TxValidationError):
+    """Rule 4: All transparent inputs require >= 2 shielded outputs."""


Should we allow 1:1? Such transactions wouldn't actually shield the value.

msbrogli · 2026-02-25T05:32:22Z

hathor/transaction/shielded_tx_output.py

+MAX_SHIELDED_OUTPUT_SCRIPT_SIZE = 1024  # Match settings.MAX_OUTPUT_SCRIPT_SIZE (VULN-001)
+
+
+class ShieldedOutputMode(IntEnum):


Rename to output mode.

msbrogli · 2026-02-25T05:33:20Z

hathor/transaction/shielded_tx_output.py

+    """Return sighash bytes for a shielded output.
+
+    Includes commitment + mode + token_data/asset_commitment + script.
+    Does NOT include proofs (range_proof, surjection_proof).


msbrogli · 2026-02-25T05:34:03Z

hathor/transaction/transaction.py

+    def has_shielded_outputs(self) -> bool:
+        """Returns true if this transaction has a shielded outputs header."""
+        try:
+            self.get_shielded_outputs_header()
+        except ValueError:
+            return False
+        else:
+            return True
+
+    def get_shielded_outputs_header(self) -> ShieldedOutputsHeader:
+        """Return the ShieldedOutputsHeader or raise ValueError."""
+        return self._get_header(ShieldedOutputsHeader)
+
+    @property
+    def shielded_outputs(self) -> list[ShieldedOutput]:
+        """Return the list of shielded outputs, or empty list if no header."""
+        if self.has_shielded_outputs():
+            return self.get_shielded_outputs_header().shielded_outputs
+        return []
+


All these methods should belong to BaseTransaction.

msbrogli · 2026-02-25T05:35:02Z

hathor/transaction/transaction.py

+            if tx_input.index < len(spent_tx.outputs):
+                spent_output = spent_tx.outputs[tx_input.index]
+            elif spent_tx.shielded_outputs:
+                shielded_idx = tx_input.index - len(spent_tx.outputs)
+                if shielded_idx < len(spent_tx.shielded_outputs):
+                    # Shielded input: skip for token info (amount is hidden)
+                    continue
+                else:
+                    # Out of bounds — will be caught by _verify_inputs
+                    continue
+            else:
+                # No shielded outputs and index out of bounds — will be caught by _verify_inputs
+                continue


Why not use resolve_spent_output()?

msbrogli · 2026-02-25T05:36:13Z

hathor/verification/verification_service.py

+        """Shielded verifications that don't need storage."""
+        try:
+            self.verifiers.shielded_tx.verify_shielded_outputs(tx)
+        except Exception:


Why Exception?

msbrogli · 2026-02-25T05:36:55Z

hathor/verification/verification_service.py

            assert self._settings.ENABLE_NANO_CONTRACTS
            # nothing to do

+        if isinstance(vertex, Transaction) and vertex.has_shielded_outputs():


You don't have to check for the vertex type since all of them have shielded outputs.

msbrogli · 2026-02-25T05:37:43Z

hathor/verification/vertex_verifier.py

                if params.features.fee_tokens:
                    allowed_headers.add(FeeHeader)
+                # CONS-006: Token creation txs must NOT allow shielded outputs,
+                # as it bypasses minting verification when combined with verify_sum skip.


Remove "as it bypasses minting verification when combined with verify_sum skip".

msbrogli · 2026-02-25T05:38:34Z

hathor/verification/vertex_verifier.py


+        # CONS-025: verify headers are in canonical order (ascending VertexHeaderId)
+        if len(vertex.headers) > 1:
+            ids = [self._get_header_order(h) for h in vertex.headers]


Why not simply use the header index?

msbrogli · 2026-02-25T05:39:32Z

hathor/verification/vertex_verifiers.py

            token_creation_tx=token_creation_tx_verifier,
            nano_header=nano_header_verifier,
            on_chain_blueprint=on_chain_blueprint_verifier,
+            shielded_tx=shielded_tx_verifier,


There's no need for a shielded transaction verifier. Split the verifiers according to the vertex type, instead.

msbrogli · 2026-02-25T05:40:44Z

hathor/wallet/resources/thin_wallet/address_balance.py

                for tx_input in tx.inputs:
                    tx2 = self.manager.tx_storage.get_transaction(tx_input.tx_id)
+                    # CONS-021: skip shielded outputs — hidden amounts
+                    if tx2.is_shielded_output(tx_input.index):


Should we add an "at least one shielded output" marker? If yes, it should be added to the response.

msbrogli · 2026-02-25T05:41:19Z

hathor/wallet/resources/thin_wallet/address_search.py

        for tx_input in tx.inputs:
            spent_tx = tx.get_spent_tx(tx_input)
+            # CONS-022: skip shielded outputs
+            if spent_tx.is_shielded_output(tx_input.index):


Same here. Should we add a marker to the response?

msbrogli · 2026-02-25T05:42:02Z

hathor/wallet/resources/send_tokens.py

+        features = Features.from_vertex(
+            settings=self._settings,
+            feature_service=self.manager.feature_service,
+            vertex=best_block,
+        )
+        params = VerificationParams.default_for_mempool(best_block=best_block, features=features)


Why this change? Doesn't VerificationParams already do it if features is not provided?

msbrogli · 2026-02-25T05:43:21Z

hathor/wallet/base_wallet.py

            new_input = None
            output_tx = tx_storage.get_transaction(_input.tx_id)
+            # CONS-023: skip shielded outputs
+            if output_tx.is_shielded_output(_input.index):


If the wallet is sending an input, it should be able to rewind the value and token id. So there would be no need to skip these.

msbrogli · 2026-02-25T05:43:41Z

hathor/wallet/base_wallet.py

            assert tx.storage is not None
            output_tx = tx.storage.get_transaction(_input.tx_id)
+            # CONS-023: skip shielded outputs
+            if output_tx.is_shielded_output(_input.index):


msbrogli · 2026-02-25T05:44:31Z

hathor/wallet/base_wallet.py

+        expected_tag = derive_tag(token_id)
+        expected_commitment = create_asset_commitment(expected_tag, asset_bf)


Shouldn't it be done by derive_tag() itself?

msbrogli · 2026-02-25T05:45:31Z

hathor/wallet/base_wallet.py

+                # Get wallet private key for this address
+                private_key = self.get_private_key(script_type_out.address)
+                privkey_bytes, _ = extract_key_bytes(private_key)
+
+                # ECDH shared secret and deterministic nonce
+                shared_secret = derive_ecdh_shared_secret(privkey_bytes, output.ephemeral_pubkey)
+                nonce = derive_rewind_nonce(shared_secret)
+
+                # Determine generator for range proof rewind
+                if isinstance(output, AmountShieldedOutput):
+                    token_index = output.token_data & 0x7F
+                    token_uid = tx.get_token_uid(token_index)
+                    # Normalize to 32 bytes
+                    if len(token_uid) < 32:
+                        token_uid = token_uid.ljust(32, b'\x00')
+                    generator = derive_asset_tag(token_uid)
+                elif isinstance(output, FullShieldedOutput):
+                    generator = output.asset_commitment
+                else:
+                    continue


Refactor this and add a method in the shielded output that receives the private key and do it all.

msbrogli · 2026-02-25T05:46:55Z

hathor-ct-crypto/src/types.rs

+pub type TokenUid = [u8; 32];
+
+/// Zero token UID representing HTR.
+pub const HTR_TOKEN_UID: TokenUid = [0u8; 32];


Can we keep it with one byte?

github-actions · 2026-02-27T16:43:22Z

Bencher Report

Branch	feat/ct-amount-token-privacy
Testbed	ubuntu-22.04

Click to view all benchmark results

Benchmark	Latency	Benchmark Result minutes (m) (Result Δ%)	Lower Boundary minutes (m) (Limit %)	Upper Boundary minutes (m) (Limit %)
sync-v2 (up to 20000 blocks)	📈 view plot 🚷 view threshold	1.64 m (-4.23%) Baseline: 1.71 m	1.54 m (93.98%)	2.05 m (79.81%)

🐰 View full continuous benchmarking report in Bencher

msbrogli self-assigned this Feb 24, 2026

msbrogli requested a review from jansegre as a code owner February 24, 2026 21:17

msbrogli added this to Hathor Network Feb 24, 2026

github-project-automation bot moved this to Todo in Hathor Network Feb 24, 2026

msbrogli force-pushed the feat/ct-amount-token-privacy branch from c497c48 to ecc157e Compare February 25, 2026 04:47

msbrogli moved this from Todo to In Progress (WIP) in Hathor Network Feb 25, 2026

msbrogli commented Feb 25, 2026

View reviewed changes

msbrogli force-pushed the feat/ct-amount-token-privacy branch from b2e8bc2 to c4c24e5 Compare February 27, 2026 16:36

msbrogli force-pushed the feat/ct-amount-token-privacy branch from c4c24e5 to bbb35b5 Compare February 27, 2026 16:50

msbrogli added 2 commits February 27, 2026 12:51

feat(tx): Add shielded output models and infrastructure

04eb6a0

feat(tx): Add shielded crypto verification and tests

2fb3a04

msbrogli force-pushed the feat/ct-amount-token-privacy branch from bbb35b5 to 2fb3a04 Compare February 27, 2026 18:51



		class TrivialCommitmentError(TxValidationError):
		"""Rule 4: All transparent inputs require >= 2 shielded outputs."""

		MAX_SHIELDED_OUTPUT_SCRIPT_SIZE = 1024 # Match settings.MAX_OUTPUT_SCRIPT_SIZE (VULN-001)


		class ShieldedOutputMode(IntEnum):

		expected_tag = derive_tag(token_id)
		expected_commitment = create_asset_commitment(expected_tag, asset_bf)

Conversation

msbrogli commented Feb 24, 2026

Motivation

Acceptance Criteria

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msbrogli Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msbrogli Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

msbrogli Feb 25, 2026 •

edited

Loading

msbrogli Feb 25, 2026 •

edited

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading