Skip to content

feat: domain access control and runtime specific code #67

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
rushby merged 9 commits into from
Nov 17, 2025
Merged

feat: domain access control and runtime specific code #67

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
9e69ac9
feat: domain access control and runtime specific code
rushby Nov 12, 2025
4fc0402
chore: update readme, add requireVersionAtLeast helper, fix runtime test
rushby Nov 13, 2025
3437367
chore: tidy up runtime utils
rushby Nov 13, 2025
ea7f19b
chore: updates following reviews
rushby Nov 14, 2025
b17ca84
chore: use api.consts.system.version for runtime version and spec
rushby Nov 16, 2025
500ca34
chore: remove domain state change check on test
rushby Nov 16, 2025
647b244
chore: remove unneeded test code
rushby Nov 16, 2025
5abe6c8
chore: update LastRuntimeUpgrade to be RuntimeSpec
rushby Nov 17, 2025
99b6ee7
chore: fix test to hold domain before unregistering
rushby Nov 17, 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
145 changes: 106 additions & 39 deletions DOCS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,68 +3,97 @@

The `zkverifyjs` package is a TypeScript library designed to facilitate sending proofs to zkVerify for verification, listening for transaction events, and waiting for transaction finalization. The package is built with an intuitive API that allows developers to handle real-time transaction events and await final results.

Currently the following proof verifiers are supported:
### Supported Proof Systems

* FFlonk
* Groth16 (BN128, BN254, BLS12-381 elliptic curves - snarkjs, arkworks, gnark libraries)
* Note - Must include `Library` and `CurveType` e.g.
The following zero-knowledge proof systems are supported:

### FFlonk

```typescript
.groth16({
library: Library.snarkjs,
curve: CurveType.bls12381
})
session.verify().fflonk().execute({...})
```

* Plonky2
* Must be an uncompressed proof include hashFunction
### Groth16

Supports multiple library and curve combinations:

**Supported Elliptic Curves:**

* BN128
* BN254
* BLS12-381

**Supported Libraries:**

* snarkjs
* arkworks
* gnark

```typescript
const { events, transactionResult } = await session
.verify()
.plonky2({
hashFunction: Plonky2HashFunction.Poseidon
})
.execute({...})
session.verify().groth16({
library: Library.snarkjs, // or Library.arkworks, Library.gnark
curve: CurveType.bls12381 // or CurveType.bn128, CurveType.bn254
}).execute({...})
```

* Risc0 versions `V2_1`, `V2_2`, `V2_3`, `V3_0`
* Note - Version must be included for Risc0 e.g.
### Plonky2

Must be an uncompressed proof. Requires hash function specification.

```typescript
.risc0({
version: Risc0Version.V2_1
})
session.verify().plonky2({
hashFunction: Plonky2HashFunction.Poseidon
}).execute({...})
```

* Ultraplonk - must include number of public inputs
### Risc0

```shell
const { events, transactionResult } = await session
.verify()
.ultraplonk({
numberOfPublicInputs: 1
})...
Supports versions: `V2_1`, `V2_2`, `V2_3`, `V3_0`

```typescript
session.verify().risc0({
version: Risc0Version.V3_0
}).execute({...})
```

* SP1
### Ultraplonk

Requires number of public inputs.

```typescript
const { events, transactionResult } = await session
.verify()
.sp1()
.execute({...})
session.verify().ultraplonk({
numberOfPublicInputs: 1
}).execute({...})
```

* UltraHonk
### SP1

```typescript
const { events, transactionResult } = await session
.verify()
.ultrahonk()
.execute({...})
session.verify().sp1().execute({...})
```

### UltraHonk

```typescript
session.verify().ultrahonk().execute({...})
```

### Runtime Versions and Network Compatibility

The zkVerify ecosystem consists of multiple networks that may run different runtime versions:

* **zkVerify Mainnet**: Production network
* **Volta Testnet**: Testing network with latest features
* **Custom Networks**: Can run any runtime version

### Version-Dependent Features

Some features are only available on specific runtime versions. The library automatically detects the runtime version when establishing a connection and may:

1. **Require different parameters** for existing functions on certain runtime versions
2. **Block access to features** not available on older runtimes
3. **Provide clear error messages** when version requirements aren't met

## Installation

To install the package, use npm or yarn:
Expand Down Expand Up @@ -1072,11 +1101,18 @@ session.registerDomain(aggregationSize, queueSize, domainOptions, accountAddress
* register a new domain where the owner is the signer that emits a new aggregation every aggregationSize proofs and where there could be at most queueSize aggregation in waiting for publication state.

- @param `{number}` aggregationSize - The size of the aggregation, integer equal to or less than 128.
- @param `{number}` queueSize: an optional integer smaller equal than 16. 16 if it’s null.
- @param `{number}` queueSize: an optional integer smaller equal than 16. 16 if it's null.
- @param `{DomainOptions}` domainOptions: additional options required to register the domain.
* `destination`: Destination type (None or Hyperbridge)
* `aggregateRules`: Security rules for aggregation (AggregateSecurityRules)
* `proofSecurityRules`: **(v1.3.0+ REQUIRED)** Security rules for proof submission (ProofSecurityRules)
* `deliveryOwner`: Optional account address for delivery ownership
* `deliveryInput`: Required if destination is Hyperbridge
- @param `{number}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
- Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`

**Note for v1.3.0+**: The `proofSecurityRules` parameter is required for network runtimes v1.3.0+.

Note: Need to hold the currency proportional to the size of aggregations and queue. The currency will be returned if the domain is unregistered

### `zkVerifySession.holdDomain`
Expand All @@ -1103,6 +1139,37 @@ session.unregisterDomain(domainId, accountAddress?);
- @param `{number}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
- Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`

### `zkVerifySession.addDomainSubmitters`

**Available in runtime v1.3.0+ only**

```typescript
session.addDomainSubmitters(domainId, submitters, accountAddress?);
```

* Adds account addresses to the allowlist for proof submission on a domain configured with `ProofSecurityRules.OnlyAllowlisted`.
* @param `{number}` domainId - The ID of the domain.
* @param `{string[]}` submitters - Array of account addresses to add to the allowlist.
* @param `{string}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
* Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`
* @throws Will throw an error if called on runtime version < 1.3.0

### `zkVerifySession.removeDomainSubmitters`

**Available in runtime v1.3.0+ only**

```typescript
session.removeDomainSubmitters(domainId, submitters, accountAddress?);
```

* Removes account addresses from the allowlist for a domain configured with `ProofSecurityRules.OnlyAllowlisted`.
* @param `{number}` domainId - The ID of the domain.
* @param `{string[]}` submitters - Array of account addresses to remove from the allowlist.
* @param `{string}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
* Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`
* @throws Will throw an error if called on runtime version < 1.3.0
* Note: Removing the last submitter from a domain may emit a `DomainStateChanged` event.

### `zkVerifySession.api`

```typescript
Expand Down
152 changes: 112 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,88 @@

The `zkverifyjs` package is a TypeScript library designed to facilitate sending proofs to zkVerify for verification, listening for transaction events, and waiting for transaction finalization. The package is built with an intuitive API that allows developers to handle real-time transaction events and await final results.

Currently the following proof verifiers are supported:
- FFlonk
- Groth16 (BN128, BN254, BLS12-381 elliptic curves - snarkjs, arkworks, gnark libraries)
- Note - Must include `Library` and `CurveType` e.g.
## Supported Proof Systems

The following zero-knowledge proof systems are supported:

### FFlonk
```typescript
.groth16({
library: Library.snarkjs,
curve: CurveType.bls12381
})
session.verify().fflonk().execute({...})
```
- Plonky2
- Must be an uncompressed proof include hashFunction

### Groth16
Supports multiple library and curve combinations:

**Supported Elliptic Curves:**
- BN128
- BN254
- BLS12-381

**Supported Libraries:**
- snarkjs
- arkworks
- gnark

```typescript
const { events, transactionResult } = await session
.verify()
.plonky2({
hashFunction: Plonky2HashFunction.Poseidon
})
.execute({...})
session.verify().groth16({
library: Library.snarkjs, // or Library.arkworks, Library.gnark
curve: CurveType.bls12381 // or CurveType.bn128, CurveType.bn254
}).execute({...})
```
- Risc0 versions `V2_1`, `V2_2`, `V2_3`, `V3_0`
- Note - Version must be included for Risc0 e.g.

### Plonky2
Must be an uncompressed proof. Requires hash function specification.

```typescript
.risc0({
version: Risc0Version.V2_1
})
```
- Ultraplonk - must include number of public inputs
```shell
const { events, transactionResult } = await session
.verify()
.ultraplonk({
numberOfPublicInputs: 1
})...
session.verify().plonky2({
hashFunction: Plonky2HashFunction.Poseidon
}).execute({...})
```
- SP1

### Risc0
Supports versions: `V2_1`, `V2_2`, `V2_3`, `V3_0`

```typescript
const { events, transactionResult } = await session
.verify()
.sp1()
.execute({...})
session.verify().risc0({
version: Risc0Version.V3_0
}).execute({...})
```
- UltraHonk

### Ultraplonk
Requires number of public inputs.

```typescript
const { events, transactionResult } = await session
.verify()
.ultrahonk()
.execute({...})
session.verify().ultraplonk({
numberOfPublicInputs: 1
}).execute({...})
```

### SP1
```typescript
session.verify().sp1().execute({...})
```

### UltraHonk
```typescript
session.verify().ultrahonk().execute({...})
```

## Runtime Versions and Network Compatibility

The zkVerify ecosystem consists of multiple networks that may run different runtime versions:

- **zkVerify Mainnet**: Production network
- **Volta Testnet**: Testing network with latest features
- **Custom Networks**: Can run any runtime version

### Version-Dependent Features

Some features are only available on specific runtime versions. The library automatically detects the runtime version when establishing a connection and may:

1. **Require different parameters** for existing functions on certain runtime versions
2. **Block access to features** not available on older runtimes
3. **Provide clear error messages** when version requirements aren't met

# Table of Contents

- [Installation](#installation)
Expand Down Expand Up @@ -93,6 +125,8 @@ Currently the following proof verifiers are supported:
- [zkVerifySession.registerDomain](#zkverifysessionregisterdomain)
- [zkVerifySession.holdDomain](#zkverifysessionholddomain)
- [zkVerifySession.unregisterDomain](#zkverifysessionunregisterdomain)
- [zkVerifySession.addDomainSubmitters](#zkverifysessionadddomainsubmitters) (v1.3.0+)
- [zkVerifySession.removeDomainSubmitters](#zkverifysessionremovedomainsubmitters) (v1.3.0+)
- [zkVerifySession.api](#zkverifysessionapi)
- [zkVerifySession.provider](#zkverifysessionprovider)

Expand Down Expand Up @@ -1085,11 +1119,18 @@ session.registerDomain(aggregationSize, queueSize, domainOptions, accountAddress
```
- register a new domain where the owner is the signer that emits a new aggregation every aggregationSize proofs and where there could be at most queueSize aggregation in waiting for publication state.
* @param `{number}` aggregationSize - The size of the aggregation, integer equal to or less than 128.
* @param `{number}` queueSize: an optional integer smaller equal than 16. 16 if it’s null.
* @param `{number}` queueSize: an optional integer smaller equal than 16. 16 if it's null.
* @param `{DomainOptions}` domainOptions: additional options required to register the domain.
- `destination`: Destination type (None or Hyperbridge)
- `aggregateRules`: Security rules for aggregation (AggregateSecurityRules)
- `proofSecurityRules`: **(v1.3.0+ REQUIRED)** Security rules for proof submission (ProofSecurityRules)
- `deliveryOwner`: Optional account address for delivery ownership
- `deliveryInput`: Required if destination is Hyperbridge
* @param `{number}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
* Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`

**Note for v1.3.0+**: The `proofSecurityRules` parameter is required for network runtimes v1.3.0+.

Note: Need to hold the currency proportional to the size of aggregations and queue. The currency will be returned if the domain is unregistered

## `zkVerifySession.holdDomain`
Expand All @@ -1112,6 +1153,37 @@ session.unregisterDomain(domainId, accountAddress?);
* @param `{number}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
* Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`

## `zkVerifySession.addDomainSubmitters`

**Available in runtime v1.3.0+ only**

```typescript
session.addDomainSubmitters(domainId, submitters, accountAddress?);
```

* Adds account addresses to the allowlist for proof submission on a domain configured with `ProofSecurityRules.OnlyAllowlisted`.
* @param `{number}` domainId - The ID of the domain.
* @param `{string[]}` submitters - Array of account addresses to add to the allowlist.
* @param `{string}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
* Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`
* @throws Will throw an error if called on runtime version < 1.3.0

## `zkVerifySession.removeDomainSubmitters`

**Available in runtime v1.3.0+ only**

```typescript
session.removeDomainSubmitters(domainId, submitters, accountAddress?);
```

* Removes account addresses from the allowlist for a domain configured with `ProofSecurityRules.OnlyAllowlisted`.
* @param `{number}` domainId - The ID of the domain.
* @param `{string[]}` submitters - Array of account addresses to remove from the allowlist.
* @param `{string}` accountAddress - Optionally provide an account address attached to the session to send the transaction from.
* Returns `{ events: EventEmitter; transactionResult: Promise<DomainTransactionInfo> }`
* @throws Will throw an error if called on runtime version < 1.3.0
* Note: Removing the last submitter from a domain may emit a `DomainStateChanged` event.

## `zkVerifySession.api`

```typescript
Expand Down
Loading