feat: add ERC-8004 HTX parsing/validation and consolidate contract client utilities by jcabrero · Pull Request #62 · NillionNetwork/blacklight-node

jcabrero · 2026-01-30T16:38:19Z

This PR introduces support for verifying agents submited through ERC 8004. This works together with blacklight-contracts#4.

integrate ERC-8004 HTX parsing and validation flow from ABI encoded requests.
refactor shared contract client utilities into a common crate
- because we created a separate client to interact with the ERC-8004 contracts, I unified common utils like tx_submitter in a different crate.
unify simulators under a single trait
- The simulator that emits transactions for ERC 8004 and NilCC simulator work under the same trait under simulator/.

jimouris · 2026-02-05T15:29:06Z

blacklight-node/src/main.rs

-    // Parse the HTX data - UnifiedHtx automatically detects provider field
-    let verification_result = match serde_json::from_slice::<Htx>(&event.rawHTX) {
+    // Debug: log the raw HTX bytes
+    let raw_bytes: &[u8] = &event.rawHTX;


Nit: Won't raw_bytes be unused if debug isn't set? Doesn't clippy complain here? I might be wrong, not sure how tracing exptects things.

Yes, this is solved in the follow up PR.

jimouris · 2026-02-05T15:30:14Z

crates/blacklight-contract-clients/src/common/mod.rs

Is this unused?

jimouris · 2026-02-05T15:31:15Z

crates/blacklight-contract-clients/src/blacklight_client.rs

-        let rpc_url = config.rpc_url.clone();
-        let ws_url = rpc_url
-            .replace("http://", "ws://")
-            .replace("https://", "wss://");
+        let ctx = ProviderContext::with_ws_retries(
+            &config.rpc_url,
+            &private_key,
+            Some(config.max_ws_retries),
+        )
+        .await?;

-        // Build WS transport with configurable retries
-        let ws = WsConnect::new(ws_url).with_max_retries(config.max_ws_retries);
-        let signer: PrivateKeySigner = private_key.parse::<PrivateKeySigner>()?;
-        let wallet = EthereumWallet::from(signer);
-
-        // Build a provider that can sign transactions, then erase the concrete type
-        let provider: DynProvider = ProviderBuilder::new()
-            .wallet(wallet.clone())
-            .with_simple_nonce_management()
-            .with_gas_estimation()
-            .connect_ws(ws)
-            .await?
-            .erased();


Why are we changing this? Seems orthogonal to the ERC-8004 changes.

This comes related to your previous comment on removing the common/ subpath. I created a new crate to integrate with ERC 8004 smart contracts. That crate uses the same common modules to submit transactions and interact with the chain. In order to avoid repetitions in the code, I moved this to its own crate that is shared by the two other crates. Another reason to make this code common is: when you interact with a smart contract to submit transactions, the nonce is fundamental for transactions to be accepted, thus the use of the same lock is necessary to avoid transactions frontrunning others. That's why I thought the best idea was to unify the interfaces in ProviderContext.

jimouris · 2026-02-05T15:32:08Z

crates/blacklight-contract-clients/src/htx.rs

+/// ERC-8004 Validation HTX data parsed from ABI-encoded bytes.
+/// Format: `abi.encode(validatorAddress, agentId, requestURI, requestHash)`
+#[derive(Debug, Clone)]
+pub struct Erc8004Htx {


Nit: should we call this V1 as well?

I don't think there can be a V2 for this unless the standard changes. I think it can be fine so far just having a single version.

jimouris · 2026-02-05T15:32:37Z

crates/blacklight-contract-clients/src/htx.rs

 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(tag = "provider", rename_all = "camelCase")]
-pub enum Htx {
+pub enum JsonHtx {


Maybe TeeHtx or do want to have any JSON here?

I chose JSON as it is the format you parse the HTX from. The ERC 8004 comes from another smart contract invocation, and the format is not JSON but rather ABI encoded. I just differentiate how these are parsed and not the logical unit for their verification.

jimouris · 2026-02-05T15:33:35Z

crates/contract-clients-common/src/errors.rs

    #[test]
    fn test_decode_error_string() {
-        // "blacklight: unknown HTX" encoded as Error(string)
+        // "NilAV: unknown HTX" encoded as Error(string)


This probably slipped.

jimouris · 2026-02-05T15:33:40Z

crates/contract-clients-common/src/errors.rs

        // Selector: 08c379a0
        // Offset:   0000...0020 (32 bytes)
-        // Length:   0000...0012 (18 bytes = "blacklight: unknown HTX".len())
+        // Length:   0000...0012 (18 bytes = "NilAV: unknown HTX".len())


I don't know how this slipped. I am checking through the commits again because this came from a miss on a rebase.

jimouris · 2026-02-05T15:35:05Z

crates/contract-clients-common/src/lib.rs

Oh, I see you added the mod here. Is this change necessary?

jimouris · 2026-02-05T15:37:26Z

docker-compose.yml

  # Anvil - Local Ethereum testnet
  anvil:
-    image: ghcr.io/nillionnetwork/blacklight-contracts/anvil:sha-64cd680
+    image: nilanvil:latest


Is this correct?

You're right. This is not correct. Because I created multiple PRs on top of each other, this is solved in the follow up PR.

jimouris · 2026-02-05T15:38:01Z

docker-compose.yml

    networks:
      - blacklight-network
-    command: ["--accounts", "15"] # Define the number of accounts to create
+    command: ["--accounts", "20"] # Define the number of accounts to create


since this is local maybe less accounts might be better to be more lightweight?

This is a good point, I am going to reduce the number.

mfontanini · 2026-02-02T16:42:40Z

crates/blacklight-contract-clients/src/htx.rs

+impl Erc8004Htx {
+    /// Try to decode ABI-encoded ERC-8004 validation data.
+    pub fn try_decode(data: &[u8]) -> Result<Self, Erc8004DecodeError> {
+        let tuple_type = DynSolType::Tuple(vec![


Is maybe using SolType instead of DynSolType make this easier? I'd hope alloy provides a better way of doing this than trying to decode each tuple field by hand.

I've applied the change on the top-most PR to avoid having to re-rebase everything, but it is a great suggestion. Thanks!

mfontanini · 2026-02-05T16:17:36Z

crates/erc-8004-contract-clients/src/identity_registry.rs

+        Err(anyhow::anyhow!(
+            "Transfer event not found in transaction receipt"
+        ))


nit: bail! (from anyhow) is a shorthand for this. e.g. bail!("beep failed")

Same here, I've applied the change to the top-most PR to avoid having to rebase everything.

fix: ERC 8004 PR fixes

chore: restructured node

…responses feat: ERC 8004 validations responses

jcabrero · 2026-02-06T14:42:06Z

I've applied all the suggested changes and gone through everything to make sure it is all working fine. I know it may be hard to detect among such an amount of code, but they're all applied. I am merging, but if we find any issues with this implementation, I will go back to it.

jcabrero force-pushed the feat/erc_8004_validations branch from f1bc1d4 to 8e79e4c Compare January 30, 2026 16:40

jcabrero mentioned this pull request Jan 30, 2026

feat: erc8004 contracts and integration with blacklight NillionNetwork/blacklight-contracts#4

Merged

jcabrero marked this pull request as ready for review February 2, 2026 15:56

jcabrero force-pushed the feat/erc_8004_validations branch from 6ae450a to befe7e1 Compare February 4, 2026 10:31

jcabrero added 4 commits February 4, 2026 11:42

feat: integrate ERC 8004 HTX parsing and validation

4abd97b

refactor: extract shared contract client utilities into common crate

9a59f7b

chore: unified simulators under a single trait

4c8b082

chore: cleaned up htx validation for ERC-8004

ec6856a

jcabrero force-pushed the feat/erc_8004_validations branch from befe7e1 to ec6856a Compare February 4, 2026 10:43

jcabrero added 2 commits February 4, 2026 11:53

chore: move common contract utilities to a single crate

a71cdae

feat: unified contract clients

1f111d4

jcabrero changed the title ~~feat: integrate ERC 8004 HTX parsing and validation~~ feat: add ERC-8004 HTX parsing/validation and consolidate contract client utilities Feb 4, 2026

jcabrero requested review from jimouris and mfontanini February 5, 2026 08:53

jcabrero added 5 commits February 5, 2026 10:18

feat: embedded validation responses on keeper

fcbe69e

fix: improved code structure

fc0722a

feat: improved logging and codebase

cd5bad6

fix: replace notify with cancellation signal

9e98249

chore: refactored and simplified blacklight-node code

96c595d

jimouris reviewed Feb 5, 2026

View reviewed changes

mfontanini approved these changes Feb 5, 2026

View reviewed changes

jcabrero added 9 commits February 6, 2026 12:28

chore: substitute DynSolTypes with SolTypes and resturcture HTX parsing

8ed84c7

chore: use more idiomatic bail!()

6acfe4e

fix: incorrect rebase

ddbb9e6

fix: merged event L2 metrics with ERC 8004

212fe01

Merge pull request #72 from NillionNetwork/fix/erc_8004_fixes

abef85b

fix: ERC 8004 PR fixes

Merge pull request #71 from NillionNetwork/chore/restructured_node

8274738

chore: restructured node

Merge pull request #70 from NillionNetwork/feat/erc_8004_validations_…

4d61e14

…responses feat: ERC 8004 validations responses

fix: code organization and commenting

565b9da

fix: adjusted docker compose number of accounts

07752a3

jcabrero merged commit 42ae3f9 into main Feb 6, 2026
1 check passed

jcabrero deleted the feat/erc_8004_validations branch February 6, 2026 14:42

Conversation

jcabrero commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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!

jcabrero commented Feb 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

jcabrero commented Jan 30, 2026 •

edited

Loading