Feat: did:ethr resolver

.gitignore

@@ -548,4 +548,6 @@ MigrationBackup/
 tmp/
 temp/
 
-# End of https://www.toptal.com/developers/gitignore/api/visualstudio
+# End of https://www.toptal.com/developers/gitignore/api/visualstudio
+
+.idea/

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **`NetDid.Method.Ethr`** — Phase 1 implementation of the `did:ethr` DID method.
+  - **`DidEthrMethod`**: Implements `Create` and `Resolve` capabilities (advertises `Create | Resolve | ServiceEndpoints`). `Update` and `Deactivate` stubs throw `OperationNotSupportedException` (Phase 2).
+  - **`EthereumAddress`**: Derives EIP-55 checksummed Ethereum addresses from compressed secp256k1 public keys using Keccak-256 (`acryptohashnet`).
+  - **`EthrIdentifier`**: Parses method-specific identifiers supporting named networks (`mainnet`, `sepolia`, `goerli`, `polygon`), hex chain IDs (`0x…`), plain 20-byte addresses, and full 33-byte compressed public keys.
+  - **`AbiEncoder` / `AbiDecoder`**: Minimal Ethereum ABI codec for the two read-only ERC-1056 call signatures (`changed`, `identityOwner`) and all three event data layouts (`DIDOwnerChanged`, `DIDDelegateChanged`, `DIDAttributeChanged`).
+  - **`Erc1056EventParser`**: Parses raw `eth_getLogs` entries into typed events by dispatching on Keccak-256 topic hashes.
+  - **`EthrDocumentBuilder`**: Replays ERC-1056 event history (oldest-first) to construct a W3C DID Document including `#controller` + optional `#controllerKey` verification methods, delegate and attribute VMs (Secp256k1, Ed25519, X25519, Multikey), service entries, and dynamic `@context` assembly.
+  - **`DefaultEthereumRpcClient`**: JSON-RPC 2.0 HTTP client over `HttpClient`. Phase 2 write methods declared but throw `NotImplementedException`.
+  - Supports `VersionId` (resolve at a specific block number) and `VersionTime` (resolve at an ISO-8601 wall-clock time) resolution options.
+  - Detects deactivation when the last `DIDOwnerChanged` event transfers ownership to `0x000…000`.
+- **`NetDidBuilder.AddDidEthr(networks)`** — DI extension method in `NetDid.Extensions.DependencyInjection`.
+- **`VerificationMethod.AdditionalProperties`** — Added `IReadOnlyDictionary<string, JsonElement>?` to `VerificationMethod` (in `NetDid.Core`) to support `publicKeyHex` for unknown key types per the did:ethr spec.
+- New sample: `NetDid.Samples.DidEthr`.
+
 ## [1.3.0] - 2026-05-22
 
 ### Security

Directory.Packages.props

@@ -5,6 +5,7 @@
   <ItemGroup>
     <!-- Cryptography -->
     <PackageVersion Include="NSec.Cryptography" Version="24.4.0" />
+    <PackageVersion Include="acryptohashnet" Version="3.1.0" />
     <PackageVersion Include="NBitcoin.Secp256k1" Version="3.1.5" />
     <PackageVersion Include="Nethermind.Crypto.Bls" Version="1.0.5" />
     <!-- Encoding -->

README.md

@@ -7,7 +7,7 @@ A specification-compliant .NET library for Decentralized Identifiers (DIDs). Net
 
 ## Features
 
-- **DID methods**: `did:key`, `did:peer`, and `did:webvh` (implemented), `did:ethr` (planned)
+- **DID methods**: `did:key`, `did:peer`, `did:webvh` (implemented), and `did:ethr` (Create+Resolve)
 - **Eight key types**: Ed25519, X25519, P-256, P-384, P-521, secp256k1, BLS12-381 G1/G2
 - **BBS+ signatures**: Multi-message signing with selective disclosure proofs (IETF draft-10)
 - **W3C DID Core 1.0** compliant DID Document model and serialization
@@ -25,6 +25,7 @@ dotnet add package NetDid.Core
 dotnet add package NetDid.Method.Key    # did:key method
 dotnet add package NetDid.Method.Peer   # did:peer method
 dotnet add package NetDid.Method.WebVh  # did:webvh method
+dotnet add package NetDid.Method.Ethr   # did:ethr method
 dotnet add package NetDid.Extensions.DependencyInjection  # Microsoft DI integration
 ```
 
@@ -250,6 +251,95 @@ var resolved = await didPeer.ResolveAsync(result.Did.Value);
 
 Short-form-only resolution returns `notFound` (requires prior long-form exchange).
 
+## did:ethr
+
+`did:ethr` resolves DIDs anchored to any EVM-compatible blockchain via the [ERC-1056 registry contract](https://github.com/decentralized-identity/ethr-did-resolver). Create derives an Ethereum address from a secp256k1 key pair; resolve walks the on-chain event log to reconstruct the DID Document at any point in history.
+
+### Create a did:ethr
+
+```csharp
+using NetDid.Core.Crypto;
+using NetDid.Method.Ethr;
+using NetDid.Method.Ethr.Rpc;
+
+var config  = KnownNetworks.Sepolia with { RpcUrl = "https://sepolia.drpc.org" };
+var factory = DefaultEthereumRpcClientFactory.CreateDirect([config]);
+var method  = new DidEthrMethod(factory, [config], new DefaultKeyGenerator());
+
+var result = await method.CreateAsync(new DidEthrCreateOptions { Network = "sepolia" });
+
+Console.WriteLine(result.Did);
+// Output: did:ethr:sepolia:0x4b0d...
+```
+
+No on-chain transaction is required to create a `did:ethr`. The DID is derived deterministically from the secp256k1 key pair. On-chain registration (Update/Deactivate) is planned for Phase 2.
+
+### Resolve a did:ethr
+
+```csharp
+var resolved = await method.ResolveAsync(
+    "did:ethr:sepolia:0xf61c81096c96f97e95ac52a570966195ad6c90dd");
+
+var doc = resolved.DidDocument!;
+Console.WriteLine(doc.VerificationMethod![0].BlockchainAccountId);
+// eip155:11155111:0xF36cAD0fb057f01F852557317bB8aa05F8c2dF4D
+```
+
+Resolve walks the on-chain ERC-1056 event chain (owner changes, delegate keys, attribute keys, services) and builds a W3C DID Document. Key types supported: `EcdsaSecp256k1RecoveryMethod2020` (delegates), `EcdsaSecp256k1VerificationKey2019`, `Ed25519VerificationKey2020`, `X25519KeyAgreementKey2020`, `Multikey`, and unknown types via `publicKeyHex`.
+
+### Historical resolution via `?versionId`
+
+`DefaultDidUrlDereferencer` passes `?versionId` directly through to the resolver — no extra wiring needed:
+
+```csharp
+using NetDid.Core.Resolution;
+
+var dereferencer = new DefaultDidUrlDereferencer(new CompositeDidResolver([method]));
+
+// Genesis document — state before any on-chain events
+var genesis = await dereferencer.DereferenceAsync(
+    "did:ethr:sepolia:0xf61c81096c96f97e95ac52a570966195ad6c90dd?versionId=0");
+
+var doc = (DidDocument)genesis.ContentStream!;
+Console.WriteLine(doc.VerificationMethod!.Count); // 1 — only #controller
+Console.WriteLine(genesis.ContentMetadata!["nextVersionId"]); // first event block
+```
+
+`versionTime` (ISO-8601 wall-clock) is also supported.
+
+### Use an existing key
+
+```csharp
+var existingKey = keyGen.Generate(KeyType.Secp256k1);
+var signer = new KeyPairSigner(existingKey, new DefaultCryptoProvider());
+
+var result = await method.CreateAsync(new DidEthrCreateOptions
+{
+    Network     = "sepolia",
+    ExistingKey = signer   // Must be Secp256k1; works with any ISigner
+});
+```
+
+### Known networks
+
+`KnownNetworks` mirrors the [`deployments.ts`](https://github.com/decentralized-identity/ethr-did-resolver/blob/master/src/config/deployments.ts) catalogue from the JS reference resolver — correct registry addresses and `legacyNonce` flags pre-populated:
+
+| Property | Network | Chain ID | Registry |
+|---|---|---|---|
+| `KnownNetworks.Mainnet` | mainnet | 1 | `0xdCa7EF03…` |
+| `KnownNetworks.Sepolia` | sepolia | 11155111 | `0x03d5003b…` |
+| `KnownNetworks.Holesky` | holesky | 17000 | `0x03d5003b…` |
+| `KnownNetworks.Gnosis` | gno | 100 | `0x03d5003b…` |
+| `KnownNetworks.Polygon` | polygon | 137 | `0xdCa7EF03…` |
+| `KnownNetworks.Aurora` | aurora | 1313161554 | `0x63eD58B6…` |
+| + 6 more | … | … | … |
+
+All entries have `RpcUrl = ""`. Supply the endpoint with a `with` expression:
+
+```csharp
+var cfg = KnownNetworks.Mainnet with { RpcUrl = "https://mainnet.gateway.tenderly.co" };
+```
+
 ## did:webvh
 
 `did:webvh` (DID Web with Verifiable History) combines web-based hosting with a cryptographically verifiable log of all changes. Full CRUD with hash chain integrity, pre-rotation, and witness validation.
@@ -418,6 +508,11 @@ services.AddNetDid(builder =>
     builder.AddDidKey();
     builder.AddDidPeer();
     builder.AddDidWebVh();
+    builder.AddDidEthr(new Dictionary<string, string>
+    {
+        ["mainnet"] = "https://mainnet.gateway.tenderly.co",
+        ["sepolia"] = "https://sepolia.drpc.org",
+    });
     builder.AddCaching(TimeSpan.FromMinutes(15));
 });
 ```
@@ -478,18 +573,21 @@ netdid/
 │   ├── NetDid.Method.Key/                   # did:key method
 │   ├── NetDid.Method.Peer/                  # did:peer method (numalgo 0, 2, 4)
 │   ├── NetDid.Method.WebVh/                 # did:webvh method (full CRUD)
+│   ├── NetDid.Method.Ethr/                  # did:ethr method (Create + Resolve)
 │   └── NetDid.Extensions.DependencyInjection/  # Microsoft DI integration
 ├── tests/
-│   ├── NetDid.Core.Tests/                   # 305 unit tests
-│   ├── NetDid.Method.Key.Tests/             # 28 tests
-│   ├── NetDid.Method.Peer.Tests/            # 31 tests
-│   ├── NetDid.Method.WebVh.Tests/           # 70 tests
+│   ├── NetDid.Core.Tests/                   # 392 unit tests
+│   ├── NetDid.Method.Key.Tests/             # 33 tests
+│   ├── NetDid.Method.Peer.Tests/            # 40 tests
+│   ├── NetDid.Method.WebVh.Tests/           # 124 tests
+│   ├── NetDid.Method.Ethr.Tests/            # 63 tests
 │   ├── NetDid.Tests.W3CConformance/         # 175 W3C conformance tests
-│   └── NetDid.Extensions.DependencyInjection.Tests/  # 10 tests
+│   └── NetDid.Extensions.DependencyInjection.Tests/  # 11 tests
 ├── samples/
 │   ├── NetDid.Samples.DidKey/               # did:key usage examples
 │   ├── NetDid.Samples.DidPeer/              # did:peer usage examples
 │   ├── NetDid.Samples.DidWebVh/             # did:webvh CRUD examples
+│   ├── NetDid.Samples.DidEthr/              # did:ethr resolve + historical resolution
 │   └── NetDid.Samples.DependencyInjection/  # DI registration pattern
 └── netdid.sln
 ```
@@ -512,6 +610,7 @@ dotnet test
 dotnet run --project samples/NetDid.Samples.DidKey
 dotnet run --project samples/NetDid.Samples.DidPeer
 dotnet run --project samples/NetDid.Samples.DidWebVh
+dotnet run --project samples/NetDid.Samples.DidEthr
 dotnet run --project samples/NetDid.Samples.DependencyInjection
 ```
 
@@ -524,19 +623,20 @@ NetDid is developed in four phases (see [NetDidPRD.md](NetDidPRD.md) for full de
 | **I** | Core Foundation — DID Document model, crypto primitives, encoding, serialization, resolver infrastructure | Complete |
 | **II** | `did:key` and `did:peer` method implementations | Complete |
 | **III** | `did:webvh` method implementation | Complete |
-| **IV** | `did:ethr` method implementation | Planned |
+| **IV** | `did:ethr` method implementation | Create + Resolve |
 
 ## Specifications
 
 NetDid targets the following specifications:
 
-| Specification | Version | Status | Reference |
-|---|---|---|---|
-| **W3C Decentralized Identifiers (DIDs)** | v1.0 | W3C Recommendation (2022-07-19) | [w3.org/TR/did-core](https://www.w3.org/TR/did-core/) |
-| **did:key** | Latest | W3C CCG Final | [w3c-ccg.github.io/did-method-key](https://w3c-ccg.github.io/did-method-key/) |
-| **did:peer** | 2.0 | DIF Spec | [identity.foundation/peer-did-method-spec](https://identity.foundation/peer-did-method-spec/) |
-| **did:webvh** | 1.0 | DIF Recommended | [identity.foundation/didwebvh](https://identity.foundation/didwebvh/) |
-| **Data Integrity (eddsa-jcs-2022)** | — | W3C Candidate Recommendation | [w3.org/TR/vc-di-eddsa](https://www.w3.org/TR/vc-di-eddsa/) |
+| Specification | Version  | Status | Reference |
+|---|----------|---|---|
+| **W3C Decentralized Identifiers (DIDs)** | v1.0     | W3C Recommendation (2022-07-19) | [w3.org/TR/did-core](https://www.w3.org/TR/did-core/) |
+| **did:key** | Latest   | W3C CCG Final | [w3c-ccg.github.io/did-method-key](https://w3c-ccg.github.io/did-method-key/) |
+| **did:peer** | 2.0      | DIF Spec | [identity.foundation/peer-did-method-spec](https://identity.foundation/peer-did-method-spec/) |
+| **did:webvh** | 1.0      | DIF Recommended | [identity.foundation/didwebvh](https://identity.foundation/didwebvh/) |
+| **did:ethr** | 13.0.0   | DIF Spec | [github.com/decentralized-identity/ethr-did-resolver](https://github.com/decentralized-identity/ethr-did-resolver/blob/master/doc/did-method-spec.md) |
+| **Data Integrity (eddsa-jcs-2022)** | —        | W3C Candidate Recommendation | [w3.org/TR/vc-di-eddsa](https://www.w3.org/TR/vc-di-eddsa/) |
 | **BBS Signatures** | draft-10 | IETF CFRG Draft | [draft-irtf-cfrg-bbs-signatures](https://datatracker.ietf.org/doc/draft-irtf-cfrg-bbs-signatures/) |
 | **JSON Canonicalization (JCS)** | RFC 8785 | IETF Proposed Standard | [rfc-editor.org/rfc/rfc8785](https://www.rfc-editor.org/rfc/rfc8785) |
 

netdid.sln

@@ -39,6 +39,12 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NetDid.Samples.DidWebVh", "
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NetDid.Samples.DependencyInjection", "samples\NetDid.Samples.DependencyInjection\NetDid.Samples.DependencyInjection.csproj", "{E344076D-4424-4D01-83B6-020878AECF67}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NetDid.Method.Ethr", "src\NetDid.Method.Ethr\NetDid.Method.Ethr.csproj", "{6E38AC63-F516-4860-8D17-959DC0479809}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NetDid.Method.Ethr.Tests", "tests\NetDid.Method.Ethr.Tests\NetDid.Method.Ethr.Tests.csproj", "{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NetDid.Samples.DidEthr", "samples\NetDid.Samples.DidEthr\NetDid.Samples.DidEthr.csproj", "{7A6D2675-875F-49EE-9497-A15ADFE23A6A}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -229,6 +235,42 @@ Global
 		{E344076D-4424-4D01-83B6-020878AECF67}.Release|x64.Build.0 = Release|Any CPU
 		{E344076D-4424-4D01-83B6-020878AECF67}.Release|x86.ActiveCfg = Release|Any CPU
 		{E344076D-4424-4D01-83B6-020878AECF67}.Release|x86.Build.0 = Release|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Debug|x64.Build.0 = Debug|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Debug|x86.Build.0 = Debug|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Release|Any CPU.Build.0 = Release|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Release|x64.ActiveCfg = Release|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Release|x64.Build.0 = Release|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Release|x86.ActiveCfg = Release|Any CPU
+		{6E38AC63-F516-4860-8D17-959DC0479809}.Release|x86.Build.0 = Release|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Debug|x64.Build.0 = Debug|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Debug|x86.Build.0 = Debug|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Release|Any CPU.Build.0 = Release|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Release|x64.ActiveCfg = Release|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Release|x64.Build.0 = Release|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Release|x86.ActiveCfg = Release|Any CPU
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65}.Release|x86.Build.0 = Release|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Debug|x64.Build.0 = Debug|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Debug|x86.Build.0 = Debug|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Release|Any CPU.Build.0 = Release|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Release|x64.ActiveCfg = Release|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Release|x64.Build.0 = Release|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Release|x86.ActiveCfg = Release|Any CPU
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -249,5 +291,8 @@ Global
 		{C29790DD-AD66-4F4B-B971-A98914788867} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 		{1D67618D-3797-4242-8483-82C63F68C076} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 		{E344076D-4424-4D01-83B6-020878AECF67} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
+		{6E38AC63-F516-4860-8D17-959DC0479809} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{AE6B1BAB-9D65-40D4-B670-526DF4C88A65} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
+		{7A6D2675-875F-49EE-9497-A15ADFE23A6A} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 	EndGlobalSection
 EndGlobal

samples/NetDid.Samples.DidEthr/NetDid.Samples.DidEthr.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../src/NetDid.Method.Ethr/NetDid.Method.Ethr.csproj" />
+    <ProjectReference Include="../../src/NetDid.Core/NetDid.Core.csproj" />
+  </ItemGroup>
+
+</Project>