feat(docker): add hathor-ct-crypto Rust library build to Dockerfile

Install Rust via rustup (distro cargo is too old for PyO3 0.22) and
build the confidential transaction crypto bindings with maturin so
hathor_ct_crypto is available in the production Docker image.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: msbrogli

.claude/skills/consensus/SKILL.md

@@ -0,0 +1,33 @@
+---
+description: "Investigate the consensus algorithm, voided transactions, best chain selection, reorgs, and accumulated weight in the DAG"
+---
+
+# Consensus Algorithm
+
+When the user asks about consensus, voided transactions, best chain, or reorgs, follow these steps:
+
+## Step 1: Read the consensus core
+- `hathor/consensus/consensus.py` — main `Consensus` class, entry point for consensus updates
+- `hathor/consensus/block_consensus.py` — block consensus (best chain selection, reorgs)
+- `hathor/consensus/transaction_consensus.py` — transaction consensus (conflict resolution, voidance)
+
+## Step 2: Understand voidance
+A vertex becomes "voided" when:
+- It conflicts with another vertex (double-spend) and loses
+- It is in a side chain (not on the best block chain)
+- Its parents/inputs are voided (voidance propagates)
+Check `transaction_metadata.py` for the `voided_by` field and how it's updated.
+
+## Step 3: Understand best chain selection
+The best chain is determined by accumulated weight:
+- Each block accumulates the weight of itself plus all transactions that confirm it
+- The chain with highest accumulated weight wins
+- Reorgs happen when a competing chain surpasses the current best chain
+
+## Step 4: Check related files
+- `hathor/transaction/transaction_metadata.py` — metadata fields: `voided_by`, `first_block`, `accumulated_weight`
+- `hathor/consensus/consensus_algorithm.py` — if it exists, may contain additional logic
+- `hathor/indexes/` — indexes that track consensus state
+
+## Step 5: Explain the specific scenario
+If the user is asking about a specific scenario (e.g., why a tx was voided, how a reorg works), trace through the consensus code path step by step.

.claude/skills/dag-structure/SKILL.md

@@ -0,0 +1,36 @@
+---
+description: "Investigate DAG architecture, parent selection, weight/difficulty calculation, DAA algorithm, and graph traversal"
+---
+
+# DAG Architecture & Weight
+
+When the user asks about the DAG structure, weight, difficulty, or parent selection, follow these steps:
+
+## Step 1: Understand the DAG model
+- Hathor uses a DAG (Directed Acyclic Graph) where both blocks and transactions are vertices
+- Each vertex references parent vertices (blocks reference block parents, transactions reference tx parents)
+- Read `hathor/transaction/base_transaction.py` for the parent fields
+
+## Step 2: Read the DAA (Difficulty Adjustment Algorithm)
+- `hathor/daa.py` — DAA calculates mining difficulty
+- Understand how weight/difficulty is adjusted based on block timestamps
+- Check the target time between blocks and adjustment window
+
+## Step 3: Understand weight
+- Each vertex has a `weight` field representing the computational work
+- Blocks have higher minimum weight than transactions
+- Accumulated weight is used for consensus (best chain selection)
+
+## Step 4: Check parent selection
+- How are parents selected for new transactions and blocks?
+- Transactions select tips from the mempool
+- Blocks select the best block as parent
+- Look for parent selection logic in vertex creation code
+
+## Step 5: Check graph traversal utilities
+- Look for BFS/DFS traversal utilities
+- How are ancestors and descendants found?
+- `hathor/consensus/` uses graph traversal extensively
+
+## Step 6: Explain
+Present the DAG mechanism or calculation relevant to the user's question with specific code references.

.claude/skills/event-system/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: "Investigate the event system, WebSocket protocol, pub/sub, event types, and event streaming in hathor-core"
+---
+
+# Event System & WebSocket
+
+When the user asks about events, WebSocket, or pub/sub, follow these steps:
+
+## Step 1: Read the event module
+- `hathor/event/` — event system implementation
+- Understand event types and how they're generated
+- Check event storage and retrieval
+
+## Step 2: Read the WebSocket module
+- `hathor/websocket/` — WebSocket protocol implementation
+- Understand the WebSocket message format
+- Check subscription/filtering mechanisms
+
+## Step 3: Read the pub/sub system
+- `hathor/pubsub.py` — publish/subscribe system for internal event distribution
+- How components subscribe to and emit events
+- Event propagation flow
+
+## Step 4: Understand event types
+- What events are emitted (new vertex, confirmation, reorg, etc.)
+- Event payload structure
+- How events relate to the transaction lifecycle
+
+## Step 5: Check event streaming
+- How events are streamed to external consumers
+- Event ordering guarantees
+- Replay and catch-up mechanisms
+
+## Step 6: Explain
+Present the event mechanism, WebSocket protocol detail, or pub/sub flow relevant to the user's question.

.claude/skills/feature-activation/SKILL.md

@@ -0,0 +1,39 @@
+---
+description: "Investigate the feature activation system, bit signaling, feature states, and feature-gated behavior in hathor-core"
+---
+
+# Feature Activation System
+
+When the user asks about feature activation, bit signaling, or feature flags, follow these steps:
+
+## Step 1: Read the core feature activation files
+- `hathor/feature_activation/feature.py` — `Feature` enum listing all features and their activation parameters
+- `hathor/feature_activation/feature_service.py` — `FeatureService` manages feature state transitions
+- `hathor/feature_activation/bit_signaling_service.py` — handles miner bit signaling in blocks
+
+## Step 2: Understand the state machine
+Features follow this state machine:
+```
+DEFINED → STARTED → MUST_SIGNAL → LOCKED_IN → ACTIVE
+                                            → FAILED
+```
+- `hathor/feature_activation/model/feature_state.py` — `FeatureState` enum with all states
+- Each state transition depends on block heights and signaling thresholds
+
+## Step 3: Understand bit signaling
+- Miners signal support for features by setting bits in block headers
+- Each feature is assigned a specific bit position
+- The signaling service counts bits over evaluation windows to determine if threshold is met
+
+## Step 4: Check feature-gated behavior
+Search the codebase for uses of the feature activation system:
+- Look for `is_feature_active()` or similar checks
+- Features gate new behavior that should only activate after network consensus
+
+## Step 5: Check feature configuration
+- Features have parameters: start height, timeout height, threshold percentage
+- These may differ between mainnet, testnet, and other networks
+- Check settings/configuration files for network-specific feature parameters
+
+## Step 6: Explain
+Present the feature's current state, activation criteria, and any gated behavior relevant to the user's question.

.claude/skills/mempool-rejection/SKILL.md

@@ -0,0 +1,37 @@
+---
+description: "Diagnose why a vertex was rejected from the mempool, including acceptance criteria, validation params, and rejection reasons"
+---
+
+# Why a Vertex Was Refused from Mempool
+
+When the user asks why a transaction or vertex was rejected from the mempool, follow these steps:
+
+## Step 1: Read the vertex handler
+- `hathor/vertex_handler/vertex_handler.py` — `VertexHandler` is the main entry point for accepting vertices into the node
+- Look for the `on_new_vertex` method and its validation pipeline
+
+## Step 2: Check acceptance criteria
+The vertex handler applies several checks before accepting a vertex:
+1. **Already exists** — vertex is already in storage
+2. **Verification failure** — basic or full verification fails (see verification skill)
+3. **Timestamp validation** — vertex timestamp must be within acceptable bounds
+4. **Parents validation** — parents must exist and be valid
+5. **Mempool-specific limits** — max mempool size, per-address limits, rate limiting
+6. **Hardened validation params** — stricter params for mempool acceptance vs. sync
+
+## Step 3: Check P2P mempool sync
+- `hathor/p2p/sync_v2/mempool.py` — mempool sync protocol, may reject vertices during sync
+- Check for peer-level rejection reasons
+
+## Step 4: Check mempool tips index
+- `hathor/indexes/mempool_tips_index.py` — tracks mempool tip transactions
+- May provide clues about why a transaction can't enter the mempool
+
+## Step 5: Check hardened vs. relaxed validation
+The node may use different validation parameters for:
+- Mempool acceptance (stricter) — e.g., tighter timestamp bounds
+- Sync acceptance (relaxed) — accepts vertices that are already confirmed
+Look for `HardenedVertex` or validation parameter differences.
+
+## Step 6: Explain
+Present the specific rejection reason, the check that failed, and any relevant thresholds or configuration values.

.claude/skills/mining/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: "Investigate mining, stratum protocol, block templates, merge mining, PoW verification, and nonce handling"
+---
+
+# Mining, Stratum & Block Templates
+
+When the user asks about mining, stratum, or block templates, follow these steps:
+
+## Step 1: Read the mining module
+- `hathor/mining/` — mining-related code
+- Understand block template generation
+- Check for CPU mining implementation (if any)
+
+## Step 2: Read the stratum protocol
+- `hathor/stratum/` — stratum protocol implementation for external miners
+- Understand the stratum message flow (subscribe, authorize, notify, submit)
+- Check job creation and solution validation
+
+## Step 3: Read merge mining
+- `hathor/merged_mining/` — merge mining (AuxPow) support
+- How Hathor blocks can be merge-mined with Bitcoin or other chains
+- `hathor/transaction/merge_mined_block.py` — merge-mined block structure
+
+## Step 4: Understand PoW verification
+- How proof-of-work is verified (hash below target)
+- Nonce field and how it's used
+- Weight/difficulty relationship to the target
+
+## Step 5: Check block construction
+- How transactions are selected from the mempool for inclusion
+- Block size limits, fee prioritization
+- How the coinbase/reward is constructed
+
+## Step 6: Explain
+Present the mining mechanism relevant to the user's question with specific code references.

.claude/skills/nano-contracts/SKILL.md

@@ -0,0 +1,41 @@
+---
+description: "Investigate nano contract architecture, blueprints, runner execution, storage layer, actions, and inter-contract calls"
+---
+
+# Nano Contract Architecture
+
+When the user asks about nano contracts, blueprints, runner, storage, or actions, follow these steps:
+
+## Step 1: Understand the blueprint system
+- `hathor/nanocontracts/` — main nano contracts package
+- Blueprints are contract templates that define methods, fields, and behavior
+- Look for blueprint base class and how blueprints are registered
+
+## Step 2: Read the runner
+- `hathor/nanocontracts/runner/runner.py` — `Runner` executes contract methods
+- Understand the execution model: method dispatch, argument parsing, context injection
+- Check how the runner manages contract state during execution
+
+## Step 3: Read the execution layer
+- `hathor/nanocontracts/execution/` — block-level execution orchestration
+- `hathor/nanocontracts/execution/block_executor.py` — executes NC txs within a block
+- Understand ordering, dependency resolution, and rollback on failure
+
+## Step 4: Understand storage
+- `hathor/nanocontracts/storage/` — contract storage layer
+- How contract fields/state are persisted and retrieved
+- Storage key formats, serialization, and caching
+
+## Step 5: Understand actions
+Actions represent token movements in NC transactions:
+- **Deposit** — tokens flow TO the contract (appears on output side)
+- **Withdrawal** — tokens flow FROM the contract (appears on input side)
+- **Grant/Acquire** — authority token operations
+- Check `hathor/transaction/headers/nano_header.py` for the NanoHeader structure
+
+## Step 6: Check inter-contract calls
+- If the user asks about contracts calling other contracts, look for call/invoke mechanisms in the runner
+- Check for context propagation and reentrancy protections
+
+## Step 7: Explain
+Present the architecture, execution flow, or specific mechanism relevant to the user's question.

.claude/skills/nano-execution-failure/SKILL.md

@@ -0,0 +1,36 @@
+---
+description: "Diagnose why a nano contract transaction failed execution, including NCFail exceptions, runner errors, and fuel/memory limits"
+---
+
+# Why a Nano Contract TX Failed
+
+When the user asks why a nano contract transaction failed, follow these steps:
+
+## Step 1: Identify the failure type
+Read the exception hierarchy:
+- `hathor/nanocontracts/exception.py` — all NC exception types, especially `NCFail` and its subclasses
+
+## Step 2: Check the runner error paths
+- `hathor/nanocontracts/runner/runner.py` — the `Runner` class executes contract methods; look for all places that raise `NCFail` or related exceptions
+- Check method resolution, argument validation, and return value handling
+
+## Step 3: Check the block executor
+- `hathor/nanocontracts/execution/block_executor.py` — `BlockExecutor` orchestrates NC execution during block processing
+- Look for error handling, rollback logic, and how failures are recorded
+
+## Step 4: Common failure causes
+Investigate these common failure paths:
+1. **Seqnum validation** — NC transactions must have sequential seqnum per contract
+2. **Fuel/memory limits** — resource limits that abort execution
+3. **Method not found** — calling a non-existent blueprint method
+4. **Invalid arguments** — wrong types or number of arguments
+5. **Storage errors** — reading non-existent keys, type mismatches
+6. **Action validation failures** — insufficient balance for withdrawals, invalid token operations
+7. **Blueprint-level assertions** — custom `raise NCFail(...)` in blueprint code
+
+## Step 5: Check the execution result
+- Look at how execution results are stored and how the failure is surfaced (metadata, events, API responses)
+- Check `hathor/nanocontracts/execution/result.py` if it exists
+
+## Step 6: Explain the failure chain
+Present the full failure path: what triggered the error, which check failed, and what the user can do to fix it.

.claude/skills/nano-execution-skipped/SKILL.md

@@ -0,0 +1,31 @@
+---
+description: "Investigate why a nano contract transaction was skipped during execution, including skip conditions and seqnum handling"
+---
+
+# Why a Nano Contract TX Was Skipped
+
+When the user asks why a nano contract transaction was skipped, follow these steps:
+
+## Step 1: Read the skip logic
+- `hathor/nanocontracts/execution/block_executor.py` — `BlockExecutor` contains the primary skip logic
+- `hathor/nanocontracts/execution/consensus_block_executor.py` — consensus-level executor may have additional skip conditions
+
+## Step 2: Understand skip conditions
+A nano contract transaction is skipped (not executed) when:
+1. **Voided by a previous failure** — if an earlier NC tx in the same block or chain failed, subsequent txs for the same contract may be skipped
+2. **Seqnum gap** — if the expected seqnum doesn't match (because a previous tx failed), execution is skipped but seqnum is still consumed
+3. **Contract state inconsistency** — the contract's state doesn't allow execution to proceed
+
+## Step 3: Check how skipping differs from failure
+- Skipped txs are different from failed txs: they don't execute at all, but their seqnum slot is still consumed
+- Look for `NCTxExecutionSkipped` or similar markers in the code
+- Check what metadata is set on skipped transactions
+
+## Step 4: Trace the execution flow
+Follow the block executor's loop over NC transactions in a block:
+1. For each NC tx, check if it should be executed or skipped
+2. If skipped, check what state is updated (seqnum counter, metadata)
+3. If the user has a specific scenario, trace through with their parameters
+
+## Step 5: Explain
+Present the skip condition that was triggered, why it was triggered, and what the downstream effects are (e.g., subsequent txs for the same contract will also be skipped).

.claude/skills/p2p-network/SKILL.md

@@ -0,0 +1,36 @@
+---
+description: "Investigate the P2P network protocol, peer connections, sync v2, peer discovery, and message propagation"
+---
+
+# P2P Network Protocol
+
+When the user asks about P2P networking, peer connections, sync, or message propagation, follow these steps:
+
+## Step 1: Read the core P2P files
+- `hathor/p2p/manager.py` — `ConnectionsManager` manages all peer connections
+- `hathor/p2p/protocol.py` — protocol state machine for peer connections
+- `hathor/p2p/states/` — protocol states (HELLO, PEER_ID, READY, etc.)
+
+## Step 2: Understand the sync protocol
+- `hathor/p2p/sync_v2/` — sync v2 implementation (current sync protocol)
+- Look for `SyncV2Protocol` or similar classes
+- Understand how nodes exchange block and transaction data
+- Check `hathor/p2p/sync_v2/mempool.py` for mempool synchronization
+
+## Step 3: Check peer discovery
+- How peers find each other (DNS seeds, bootstrap nodes, peer exchange)
+- Peer management: connection limits, peer scoring, ban logic
+
+## Step 4: Check message types
+- Look for message definitions and handlers
+- Understand the message serialization format
+- Check how vertices are propagated to peers
+
+## Step 5: Check connection lifecycle
+- Connection establishment (TCP, TLS)
+- Handshake protocol (version negotiation, capabilities exchange)
+- Connection maintenance (heartbeat/ping-pong)
+- Disconnection handling
+
+## Step 6: Explain
+Present the relevant P2P mechanism, protocol flow, or configuration based on the user's specific question.