npm package: @nebrazkp/upa
Description: UPA contracts, client SDK and tools
Latest version: 2.0.3

# 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](#release-notes)

## Requirements

- node.js>=18

## Installation

```console
$ yarn add @nebrazkp/upa
```

Run the `upa` tool
```console
$ ./node_modules/bin/upa --help
```

### Development

See [DEVELOPMENT.md].

## Release notes

### V2.0.3
Support for off-chain verifier services in the upa tool.

### V2.0.2
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.