Skip to content

feat(EVM-PA): use permalinks and small improvements #374

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonaprieto merged 2 commits into from
Jun 3, 2025
Merged

feat(EVM-PA): use permalinks and small improvements #374

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
32c7ca8
feat: use permalinks and small improvements
heueristik May 30, 2025
0d9cda3
Merge branch 'main' into michael/evm-pa-update
jonaprieto Jun 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 16 additions & 23 deletions docs/arch/integrations/adapters/evm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,25 +34,25 @@ Only the protocol adapter can call [non-view functions](https://docs.soliditylan

### Commitment Accumulator

The implementation uses a modified version of the [OpenZeppelin `MerkleTree` v.5.2.0](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.2.0/contracts/utils/structs/MerkleTree.sol) that populates the binary tree from left to right and stores leaf indices in a hash table
The [implementation](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/state/CommitmentAccumulator.sol) uses a modified version of the [OpenZeppelin `MerkleTree` v.5.2.0](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.2.0/contracts/utils/structs/MerkleTree.sol) that populates the binary tree from left to right and [stores commitment indices in a hash table](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/state/CommitmentAccumulator.sol#L21)

```solidity
mapping(bytes32 commitment => uint256 index) internal _indices;
```

allowing for commitment existence checks.

In addition to the leaves, the [modified implementation](https://github.com/anoma/evm-protocol-adapter/blob/main/src/state/CommitmentAccumulator.sol) stores also the intermediary node hashes.
In addition to the leaves, the [modified Merkle tree implementation](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/libs/MerkleTree.sol) stores also the intermediary node hashes, which allows to [obtain Merkle proofs directly from the contract](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/libs/MerkleTree.sol#L88-L136).

Historical Merkle tree roots are stored in an [OpenZeppelin `EnumerableSet` v5.2.0](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.2.0/contracts/utils/structs/EnumerableSet.sol) allowing for existence checks.

### Nullifier Set

The implementation uses an [OpenZeppelin `EnumerableSet` v5.2.0](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.2.0/contracts/utils/structs/EnumerableSet.sol) to store nullifiers of consumed resources and allow for existence checks.
The [implementation](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/state/NullifierSet.sol) uses an [OpenZeppelin `EnumerableSet` v5.2.0](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.2.0/contracts/utils/structs/EnumerableSet.sol) to store nullifiers of consumed resources and allow for existence checks.

### Blob Storage

The [implementation](https://github.com/anoma/evm-protocol-adapter/blob/main/src/state/BlobStorage.sol) uses a simple hash table to store blobs content-addressed.
The [implementation](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/state/BlobStorage.sol) uses a simple hash table to store blobs content-addressed.

```solidity
mapping(bytes32 blobHash => bytes blob) internal _blobs;
Expand All @@ -73,7 +73,7 @@ For hashing, we compute the SHA-256 hash of the [strictly ABI-encoded](https://d

## Types & Computable Components

The RM-related type and computable component definitions in Solidity can be found in the [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/Types.sol) and [`src/libs/ComputableComponents.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/libs/ComputableComponents.sol) file, respectively.
The RM-related type and computable component definitions in Solidity can be found in the [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/Types.sol) and [`src/libs/ComputableComponents.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/libs/ComputableComponents.sol) file, respectively.

## Proving Systems

Expand All @@ -85,18 +85,19 @@ For proof verification, we use the [RISC ZERO verifier contracts](https://dev.ri

For the current prototype and the only supported example application [basic shielded Kudos ](https://research.anoma.net/t/basic-e2e-shielded-kudos-app/1237), we use a specific circuit resulting in the loss of function privacy. This will be improved in future iterations.

The associated types are defined in [`proving/Compliance.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/proving/Compliance.sol).
The associated types are defined in [`proving/Compliance.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/proving/Logic.sol).

### Compliance Proofs

Compliance units have a fixed size and contain references to one consumed and one created resource. For transaction with $n_\text{consumed} \neq n_\text{created}$, we expect padding resources (ephemeral resources with quantity 0) to be used.

The associated types are defined in [`proving/Compliance.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/proving/Compliance.sol).
The associated types are defined in [`proving/Compliance.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/proving/Compliance.sol).

### Delta Proofs

The delta values are computed as 2D points (`uint256[2]`) on the `secp256k1` (K-256) curve and can be verified using ECDSA.
The delta values are computed as 2D points (`uint256[2]`) on the `secp256k1` (K-256) elliptic curve and can be verified using ECDSA.

The associated elliptic curve addition and conversion methods are defined in [`proving/Delta.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/proving/Delta.sol).
The curve implementation is taken from [Witnet's `eliptic-curve-solidity` library v0.2.1](https://github.com/witnet/elliptic-curve-solidity/tree/0.2.1). This includes

- [curve parameters](https://github.com/witnet/elliptic-curve-solidity/blob/0.2.1/examples/Secp256k1.sol)
Expand All @@ -105,15 +106,9 @@ The curve implementation is taken from [Witnet's `eliptic-curve-solidity` librar

We use the zero delta public key derived from the private key `0`.

As the message digest, we use the transaction hash that we've defined as follows (see [`src/ProtocolAdapter.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/ProtocolAdapter.sol)):
As the verifying key (a.k.a. message digest), we use the keccak-256 hash over the list of all nullifier and commitments pairs being obtained by iterating over the compliance units (see [`src/proving/Delta.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/proving/Delta.sol#L31-L37)).

```solidity
function _transactionHash(bytes32[] memory tags) internal pure returns (bytes32 txHash) {
txHash = sha256(abi.encode(tags));
}
```

For key recovery from the message digest and signature, we use [OpenZeppelin's `ECDSA` library](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/cryptography/ECDSA.sol).
For key recovery from the verifying key and signature, we use [OpenZeppelin's `ECDSA` library](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/cryptography/ECDSA.sol).

## EVM and RM State Correspondence

Expand Down Expand Up @@ -143,7 +138,7 @@ and allows the application to ensure the correspondence.

This works as follows:

The protocol adapter accepts an optional `ForwarderCalldata` struct with the RM transaction object as part of the action object (see [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/Types.sol)):
The protocol adapter accepts an optional `ForwarderCalldata` struct with the RM transaction object as part of the action object (see [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/Types.sol#L46-L53)):

```solidity
struct ForwarderCalldata {
Expand Down Expand Up @@ -193,9 +188,7 @@ Besides referencing the external contract by its address, the forwarder contract
the resource kind of the associated [calldata carrier resource](#calldata-carrier-resource) that the protocol adapter will require be created. This allows the forwarder contract to also to enforce its own contract address to be part of the carrier resource label, which ensures that the correspondence between the forwarder and carrier resource is unique.

!!! note
The mutual dependency between
- the calldata carrier resource label containing the forwarder contract address
- the forwarder contract referencing the calldata carrier resource label
The mutual dependency between - the calldata carrier resource label containing the forwarder contract address - the forwarder contract referencing the calldata carrier resource label

can be established by deterministic deployment or post-deployment initialization of the forwarder contract.

Expand Down Expand Up @@ -225,7 +218,7 @@ contract ExampleForwarder is Ownable {
}
```

The required calldata is passed with the RM transaction object as part of the `Action` struct (see [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/Types.sol)).
The required calldata is passed with the RM transaction object as part of the `Action` struct (see [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/Types.sol#L43)).

```solidity
struct ForwarderCalldata {
Expand All @@ -247,7 +240,7 @@ function _executeForwarderCall(ForwarderCalldata calldata call) internal {
}
```

The forwarder contract base class can be found in [`src/ForwarderBase.sol`](https://github.com/anoma/evm-protocol-adapter/blob/main/src/ForwarderBase.sol).
The forwarder contract base class can be found in [`src/ForwarderBase.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/forwarders/ForwarderBase.sol).

### Calldata Carrier Resource

Expand All @@ -257,7 +250,7 @@ By default, calldata carrier resources can be consumed by everyone (because thei
!!! note
When the singleton calldata carrier resource is consumed in a transaction, subsequent transactions in the same block cannot consume it anymore. This effectively limits the current design to a single forwarder contract call per block (if the commitment of the latest, unspent calldata carrier resource is not known to the subsequent transaction ahead of time). This will be improved in upcoming protocol adapter versions.

The calldata carrier resource object is passed to the protocol adapter together with the `ForwarderCalldata` struct (see [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6cdf69b92f58d56dc13df1c0b52539295ea59814/src/Types.sol#L31)):
The calldata carrier resource object is passed to the protocol adapter together with the `ForwarderCalldata` struct (see [`src/Types.sol`](https://github.com/anoma/evm-protocol-adapter/blob/6f7cde40aaec5e385408012269b85bb8173a9b87/contracts/src/Types.sol#L55-L64)):


```solidity
Expand Down
Loading