feat(nano): add Nano Runtime V2 feature

Author: glevco

hathor/consensus/consensus.py

@@ -106,6 +106,7 @@ def __init__(
             runner_factory=runner_factory,
             nc_storage_factory=nc_storage_factory,
             nc_calls_sorter=nc_calls_sorter,
+            feature_service=feature_service,
         )
 
         # Create NCConsensusBlockExecutor (with side effects) for consensus
@@ -456,6 +457,9 @@ def _feature_activation_rules(self, tx: Transaction, new_best_block: Block) -> b
                 case Feature.OPCODES_V2:
                     if not self._opcodes_v2_activation_rule(tx):
                         return False
+                case Feature.NANO_RUNTIME_V2:
+                    # This feature does not affect verification, only the Nano runtime.
+                    pass
                 case (
                     Feature.INCREASE_MAX_MERKLE_PATH_LENGTH
                     | Feature.NOP_FEATURE_1

hathor/dag_builder/vertex_exporter.py

@@ -283,6 +283,8 @@ def create_vertex_block(self, node: DAGNode) -> Block:
             blk.weight = float(node.attrs['weight'])
         else:
             blk.weight = self._daa.calculate_block_difficulty(blk, self.get_parent_block)
+        if 'signal_bits' in node.attrs:
+            blk.signal_bits = int(node.attrs['signal_bits'])
         self.update_vertex_hash(blk)
         self._block_height[blk.hash] = height
         return blk

hathor/feature_activation/feature.py

@@ -33,3 +33,4 @@ class Feature(StrEnum):
     NANO_CONTRACTS = 'NANO_CONTRACTS'
     FEE_TOKENS = 'FEE_TOKENS'
     OPCODES_V2 = 'OPCODES_V2'
+    NANO_RUNTIME_V2 = 'NANO_RUNTIME_V2'

hathor/feature_activation/utils.py

@@ -19,6 +19,7 @@
 
 from hathor.feature_activation.feature import Feature
 from hathor.feature_activation.model.feature_state import FeatureState
+from hathor.nanocontracts.nano_runtime_version import NanoRuntimeVersion
 from hathor.transaction.scripts.opcode import OpcodesVersion
 
 if TYPE_CHECKING:
@@ -36,6 +37,7 @@ class Features:
     nanocontracts: bool
     fee_tokens: bool
     opcodes_version: OpcodesVersion
+    nano_runtime_version: NanoRuntimeVersion
 
     @staticmethod
     def from_vertex(*, settings: HathorSettings, feature_service: FeatureService, vertex: Vertex) -> Features:
@@ -47,6 +49,7 @@ def from_vertex(*, settings: HathorSettings, feature_service: FeatureService, ve
             Feature.NANO_CONTRACTS: settings.ENABLE_NANO_CONTRACTS,
             Feature.FEE_TOKENS: settings.ENABLE_FEE_BASED_TOKENS,
             Feature.OPCODES_V2: settings.ENABLE_OPCODES_V2,
+            Feature.NANO_RUNTIME_V2: settings.ENABLE_NANO_RUNTIME_V2,
         }
 
         feature_is_active: dict[Feature, bool] = {
@@ -55,12 +58,16 @@ def from_vertex(*, settings: HathorSettings, feature_service: FeatureService, ve
         }
 
         opcodes_version = OpcodesVersion.V2 if feature_is_active[Feature.OPCODES_V2] else OpcodesVersion.V1
+        nano_runtime_version = (
+            NanoRuntimeVersion.V2 if feature_is_active[Feature.NANO_RUNTIME_V2] else NanoRuntimeVersion.V1
+        )
 
         return Features(
             count_checkdatasig_op=feature_is_active[Feature.COUNT_CHECKDATASIG_OP],
             nanocontracts=feature_is_active[Feature.NANO_CONTRACTS],
             fee_tokens=feature_is_active[Feature.FEE_TOKENS],
             opcodes_version=opcodes_version,
+            nano_runtime_version=nano_runtime_version,
         )
 
     @staticmethod
@@ -69,20 +76,23 @@ def for_mempool(*, settings: HathorSettings, feature_service: FeatureService, be
         Used for mempool verification.
 
         Features can either be more restrictive (for example, `count_checkdatasig_op`) or more permissive
-        (for example, `nanocontracts`).
+        (for example, `nanocontracts`) in relation to vertex verification. When a feature doesn't affect
+        verification, such as changes to the Nano runtime only (`nano_runtime_version`), it is indifferent.
 
         Returns information about each feature where permissive features come from the state in the provided
         block, and restrictive features are always enabled. This means restrictive features are applied in
         mempool verification regardless of features states in the current best block.
         """
         features = Features.from_vertex(settings=settings, feature_service=feature_service, vertex=best_block)
         return Features(
-            # Permissive features (come from the block state):
-            nanocontracts=features.nanocontracts,
-            fee_tokens=features.fee_tokens,
             # Restrictive features (hardcoded as enabled):
             count_checkdatasig_op=True,
             opcodes_version=OpcodesVersion.V2,
+            # Permissive features (come from the block state):
+            nanocontracts=features.nanocontracts,
+            fee_tokens=features.fee_tokens,
+            # Indifferent features (come from the block state):
+            nano_runtime_version=features.nano_runtime_version,
         )
 
     @staticmethod
@@ -91,14 +101,19 @@ def all_enabled() -> Features:
         Used mostly for APIs and tests, it disregards the actual state of the blockchain
         and hardcodes all features as enabled.
 
-        For restrictive features, this means they're restricted on APIs just like in the mempool. For permissive
-        features, they're allowed on APIs, which is fine since they may be blocked during verification anyway.
+        - For restrictive features, this means they're restricted on APIs just like in the mempool.
+        - For permissive features, they're allowed on APIs, which is fine since they may be blocked
+          during verification anyway.
+        - For indifferent features, it doesn't matter.
+
+        Read the `Features.for_mempool` docstring for more details on these types of features.
         """
         return Features(
             count_checkdatasig_op=True,
             nanocontracts=True,
             fee_tokens=True,
             opcodes_version=OpcodesVersion.V2,
+            nano_runtime_version=NanoRuntimeVersion.V2,
         )
 
 

hathor/manager.py

@@ -43,6 +43,7 @@
 from hathor.execution_manager import ExecutionManager
 from hathor.feature_activation.bit_signaling_service import BitSignalingService
 from hathor.feature_activation.feature_service import FeatureService
+from hathor.feature_activation.utils import Features
 from hathor.mining import BlockTemplate, BlockTemplates
 from hathor.mining.cpu_mining_service import CpuMiningService
 from hathor.nanocontracts.runner import Runner
@@ -410,7 +411,9 @@ def get_nc_runner(self, block: Block) -> Runner:
         """Return a contract runner for a given block."""
         nc_storage_factory = self.consensus_algorithm.nc_storage_factory
         block_storage = get_block_storage_from_block(nc_storage_factory, block)
+        features = Features.from_vertex(settings=self._settings, feature_service=self.feature_service, vertex=block)
         return self.runner_factory.create(
+            runtime_version=features.nano_runtime_version,
             block_storage=block_storage,
         )
 

hathor/nanocontracts/blueprint_env.py

@@ -17,6 +17,7 @@
 from typing import TYPE_CHECKING, Any, Collection, Sequence, TypeAlias, final
 
 from hathor.conf.settings import HATHOR_TOKEN_UID
+from hathor.nanocontracts.nano_settings import NanoSettings
 from hathor.nanocontracts.types import Amount, BlueprintId, ContractId, NCAction, NCFee, TokenUid
 
 if TYPE_CHECKING:
@@ -266,3 +267,10 @@ def setup_new_contract(
             actions=actions,
             fees=fees or (),
         )
+
+    def get_settings(self) -> NanoSettings:
+        """
+        Return the settings for the current Nano runtime.
+        Settings are not constant, they may be changed over time.
+        """
+        return self.__runner.syscall_get_nano_settings()

hathor/nanocontracts/execution/block_executor.py

@@ -21,13 +21,16 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Iterator
 
+from hathor.feature_activation.utils import Features
 from hathor.nanocontracts.exception import NCFail
+from hathor.nanocontracts.nano_runtime_version import NanoRuntimeVersion
 from hathor.transaction import Block, Transaction
 from hathor.transaction.exceptions import TokenNotFound
 from hathor.transaction.nc_execution_state import NCExecutionState
 
 if TYPE_CHECKING:
     from hathor.conf.settings import HathorSettings
+    from hathor.feature_activation.feature_service import FeatureService
     from hathor.nanocontracts.runner import Runner
     from hathor.nanocontracts.runner.runner import RunnerFactory
     from hathor.nanocontracts.sorter.types import NCSorterCallable
@@ -113,6 +116,7 @@ def __init__(
         runner_factory: 'RunnerFactory',
         nc_storage_factory: 'NCStorageFactory',
         nc_calls_sorter: 'NCSorterCallable',
+        feature_service: FeatureService,
     ) -> None:
         """
         Initialize the block executor.
@@ -127,11 +131,9 @@ def __init__(
         self._runner_factory = runner_factory
         self._nc_storage_factory = nc_storage_factory
         self._nc_calls_sorter = nc_calls_sorter
+        self._feature_service = feature_service
 
-    def execute_block(
-        self,
-        block: Block,
-    ) -> Iterator[NCBlockEffect]:
+    def execute_block(self, block: Block) -> Iterator[NCBlockEffect]:
         """Execute block as generator, yielding effects without applying them.
 
         This is the pure execution method that yields lifecycle events as it processes
@@ -169,6 +171,7 @@ def execute_block(
 
         nc_sorted_calls = self._nc_calls_sorter(block, nc_calls) if nc_calls else []
         block_storage = self._nc_storage_factory.get_block_storage(parent_root_id)
+        features = Features.from_vertex(settings=self._settings, feature_service=self._feature_service, vertex=block)
 
         yield NCBeginBlock(
             block=block,
@@ -189,6 +192,7 @@ def execute_block(
 
             # Execute transaction and yield the result directly
             result = self.execute_transaction(
+                runtime_version=features.nano_runtime_version,
                 tx=tx,
                 block_storage=block_storage,
                 rng_seed=rng_seed,
@@ -210,6 +214,7 @@ def execute_block(
     def execute_transaction(
         self,
         *,
+        runtime_version: NanoRuntimeVersion,
         tx: Transaction,
         block_storage: 'NCBlockStorage',
         rng_seed: bytes,
@@ -234,6 +239,7 @@ def execute_transaction(
             return NCTxExecutionSkipped(tx=tx)
 
         runner = self._runner_factory.create(
+            runtime_version=runtime_version,
             block_storage=block_storage,
             seed=rng_seed,
         )

hathor/nanocontracts/nano_runtime_version.py

@@ -0,0 +1,30 @@
+#  Copyright 2026 Hathor Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from enum import IntEnum
+
+
+class NanoRuntimeVersion(IntEnum):
+    """
+    The runtime version of Nano Contracts.
+    It must be updated via Feature Activation and can be used to add new syscalls, for example.
+
+    V1:
+      - Initial version
+
+    V2:
+      - Added `get_settings` syscall
+    """
+    V1 = 1
+    V2 = 2

hathor/nanocontracts/nano_settings.py

@@ -0,0 +1,24 @@
+#  Copyright 2026 Hathor Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class NanoSettings:
+    """
+    This dataclass contains information about the settings used by the current Nano runtime.
+    It is returned by the `get_settings` syscall. Note that settings are not constant, they may change over time.
+    """
+    fee_per_output: int

hathor/nanocontracts/runner/runner.py

@@ -47,6 +47,8 @@
 from hathor.nanocontracts.faux_immutable import create_with_shell
 from hathor.nanocontracts.metered_exec import MeteredExecutor
 from hathor.nanocontracts.method import Method, ReturnOnly
+from hathor.nanocontracts.nano_runtime_version import NanoRuntimeVersion
+from hathor.nanocontracts.nano_settings import NanoSettings
 from hathor.nanocontracts.rng import NanoRNG
 from hathor.nanocontracts.runner.call_info import CallInfo, CallRecord, CallType
 from hathor.nanocontracts.runner.index_records import (
@@ -125,6 +127,7 @@ def __init__(
         *,
         reactor: ReactorProtocol,
         settings: HathorSettings,
+        runtime_version: NanoRuntimeVersion,
         tx_storage: TransactionStorage,
         storage_factory: NCStorageFactory,
         block_storage: NCBlockStorage,
@@ -136,6 +139,7 @@ def __init__(
         self._storages: dict[ContractId, NCContractStorage] = {}
         self._settings = settings
         self.reactor = reactor
+        self._runtime_version = runtime_version
 
         # For tracking fuel and memory usage
         self._initial_fuel = self._settings.NC_INITIAL_FUEL_TO_CALL_METHOD
@@ -1271,6 +1275,18 @@ def syscall_change_blueprint(self, blueprint_id: BlueprintId) -> None:
         nc_storage = self.get_current_changes_tracker()
         nc_storage.set_blueprint_id(blueprint_id)
 
+    def syscall_get_nano_settings(self) -> NanoSettings:
+        """Get nano settings according to the current runtime."""
+        match self._runtime_version:
+            case NanoRuntimeVersion.V1:
+                raise NCFail('syscall `get_settings` is not yet supported')
+            case NanoRuntimeVersion.V2:
+                return NanoSettings(
+                    fee_per_output=self._settings.FEE_PER_OUTPUT,
+                )
+            case _:
+                assert_never(self._runtime_version)
+
     def _get_token(self, token_uid: TokenUid) -> TokenDescription:
         """
         Get a token from the current changes tracker or storage.
@@ -1456,12 +1472,14 @@ def __init__(
     def create(
         self,
         *,
+        runtime_version: NanoRuntimeVersion,
         block_storage: NCBlockStorage,
         seed: bytes | None = None,
     ) -> Runner:
         return Runner(
             reactor=self.reactor,
             settings=self.settings,
+            runtime_version=runtime_version,
             tx_storage=self.tx_storage,
             storage_factory=self.nc_storage_factory,
             block_storage=block_storage,