UPA contracts, client SDK and tools

UPA is Nebra's "Universal Proof Aggregator". This package contains the client SDK for buiding apps that leverage the UPA to reduce the cost of on-chain ZKP verification.

This package also includes the upa tool for interacting with UPA deployments.

Full documentation is available at docs.nebra.one.

RELEASE NOTES

Requirements

• node.js>=18

Installation

$ yarn add @nebrazkp/upa

Run the upa tool

$ ./node_modules/bin/upa --help

Development

See [DEVELOPMENT.md].

Release notes

V2.0.x

UPA V2 supports submission of Groth16 proofs to an off-chain submission endpoint, allowing users to save the gas cost of submitting on-chain. The upa tool has been updated to support this new feature.

The upa off-chain subcommand has been added to the upa tool. This subcommand allows users to perform various actions related to submitting Groth16 proofs off-chain. The upa off-chain subcommand supports the following subcommands:

• submit - Submit a set of proofs to an off-chain aggregator
• deposit - Deposit ETH into an aggregator's deposits contract
• init-withdrawal - Initiate a withdrawal
• withdraw - Withdraw deposit. Must init-withdrawal before notice period
• balance - View the balance of an address
• withdraw-at-block - View the block at which an address can withdraw
• refund-fee - Refund a submission not aggregated within agreed expiry time
• get-state - Get the submitter state held by an off-chain aggregator
• get-parameters - Get the current parameters for an off-chain aggregator

Note depositing into the aggregator's deposits contract is required before submitting proofs off-chain. This is because protocol fees can no longer be collected at submission time. Deposits can be withdrawn but there is a notice period before withdrawal is allowed, to prevent any attacks. In UPA's off-chain protocol, aggregator's agree to a block number by which the submission will be aggregated. If the submission is not aggregated by this block number, the submitter can get a fee refund.

V1.2.x

The Proof and VerifyingKey objects, representing Groth16 proofs and keys created by applications, have been renamed to Groth16Proof and Groth16VerifyingKey, to avoid ambiguity and make room for future features.

The upa deploy command now takes in a upa_config.json file. To use a test configuration instead, pass the flag --use-test-config.

CircuitIDs are now of type bytes32 instead of uint256, requiring application contracts to be updated accordingly. Support to compute it off-chain has been added to the SDK. (The computeCircuitId has been removed from UpaClient and is now available as a standalone function in the sdk.utils module.)

ProofVerified events are no longer emitted. Instead, SubmissionVerified events are emitted.

The UpaClient is now initialized using a static async init function. Its contructor is private.

The upa submit-proofs command now takes in four possible JSON proof file formats: [(circuitId, proof, inputs)], (circuitId, proof, inputs), [(vk, proof, inputs)], or (vk, proof, inputs).

V1.1.2

Added the upa tool command upa convert-proof-snarkjs.

V1.1.1

The upa tool in the SDK has been extended to include convert-vk-gnark and convert-proof-gnark commands. Groth16 proofs with accompanying commitments to witness data (including those generated by the Gnark library) are now supported by the aggregation pipeline. Note that support is limited to single commitments to non-public data, using Keccak as the hash in the hash-to-field function.

NOTE: This version of the SDK is accompanied by a new testnet deployment, and does not maintain compatibility with the v1.0.x releases.

See docs.nebra.one for further details.

v1.0.1

• upa groth16-verify tool for offline proof and input data verification
• Expose VerifyingKey in top-level namespace
• Documentation comments for more public types and functions

v1.0.0

This version of the package provides:

• A Typescript library including full support for client-side proof submission and detection of aggregation.
• Solidity contract interfaces and library for on-chain verification from application smart contracts.
• A upa CLI tools for performing operations on a deployed instance, as well as for setting up development environments for end-to-end application testing.

NOTE: The SDK defines types application.Proof and application.VerifyingKey for Groth16 verifying keys and proofs, describing the format expected for these objects. Functions to convert from keys and proofs as output from snarkjs and gnark are also included. Proofs generated by other implementations (arkworks, etc) must be converted to the application types by the caller (see the definitions of these types in application.d.ts for details).

Conversion function for more Groth16 implementations will be provided in upcoming versions.