nrpm: Noir package manager

[chancehudson]

nrpm

This document describes a package management system for Noir programs. It is composed of two components: nrpm (Noir Package Manager) and a remote system called Onyx for storing and maintaining packages and documentation.

Motivation

Zero knowledge circuits benefit disproportionately from code reuse. Generally a circuit must be audited and heavily optimized before it can be considered safe/performant for production use. To date the state of code reuse in the zero knowledge ecosystem is severely lacking. Circom supports importing files, but the developer must use git submodules or otherwise manually acquire the source files. Noir is better, supporting imports from git repositories and dependency resolution, but this still lacks immutability by default. Nargo does require a "tag" field, but the tag contents are mutable by the repository author. Indeed using a commit hash seems disallowed!

A package manager for ZK circuits makes room for visibility into the space. The current approach of using Github repositories means there is no centralized listing of packages. Having a centralized list like crates.io makes room for standardizing requests for audits, publishing publicly available verifier addresses, indicating safe backends/nargo versions, and calculating dependent packages.

Methodology

nrpm is a command line utility for loading and verifying dependency trees using a Nargo.toml file. The utility manages the dependencies on disk along with a nrpm.lock file for each package.

Onyx is a server system for publishing, cataloguing and serving content verified Noir packages.

nrdoc is a utility for auto generating html documentation from Noir packages. This utility will be used in nrpm and Onyx.

All implementations will be authored in Rust or Typescript under the MIT or Apache-2.0 license. Rust will be preferred but Typescript may be used for simple worker script implementations.

Onyx

Onyx is a server system for hosting and serving Noir packages. Similar to npmjs.com or crates.io it will present a webpage listing packages with available versions, readmes and other metadata. Onyx will support user authentication using Github oauth, or email and 2fa.

The system will consist of a relational database containing user and package data (the "db"), a key value store mapping package hashes to contents (the "hashmap"), and a web server exposing a REST api (the "server"). The server should additionally expose a mechanism for synchronizing with other instances allowing independent operators to maintain an archive of all packages and metadata and optionally serve package contents (see business model for more info).

A stretch goal would include cryptographic signatures from the authors of packages, and countersignatures from the Onyx operator. This could include the package registry index being stored in a cryptographically friendly data structure to allow ZK statements in the future. The details of this implementation are left out of scope for this proposal.

nrpm

nrpm contains three commands, install, publish and docs. nargo will be used for all other operations including compiling and proving.

nrpm install handles reading the Nargo.toml file, downloading dependencies, verifying content hashes, and updating the nrpm.lock file. Dependencies will be resolved and placed in the system nargo package directory. A subsequent nargo compile invocation will use the existing packages. Note: as a precaution nargo compile should accept an optional flag like --no-resolve that forces it to bail if a dependency is not locally found. This will allow inconsistencies between nrpm and nargo to more readily be detected.

nrpm publish allows developers to publish packages to the Onyx registry. nrpm will authenticate the user with a web challenge to obtain an authentication token for Onyx. nrpm will then create a tarball from the contents of the directory and upload to Onyx. If any dependent packages rely on github based storage a warning will be shown.

nrpm docs allows developers to preview auto-generated documentation for their Noir source files. Docs will be generated on the Onyx server for each new package version.

Nargo compatibility

The nrpm/Onyx system will be fully compatible with Nargo as it currently exists. Onyx will expose packages as a mocked git endpoint. A dependency from Onyx would be specified as follows:

my-package = { git = "https://onyxzk.com/my-package", tag = "0.1.0" }

Onyx will support version ranges like ^0.1.0 by resolving the tag to a compliant version and returning the contents.

nrdoc

nrdoc is a utility library for generating html documentation from comments in Noir source files. This concept is based heavily on the docs.rs implementation for Rust packages.

Business Model

The described system is intended to be implemented on Cloudflare to avoid infrastructure management complexity. The db will be hosted on D1, the hashmap stored in R2, and the REST api implemented using workers.

Using NPM numbers for reference:

• total packages: 3,500,000
• downloads per month: 257,725,329,708
• package versions published per month: 500,000
• average package size: 500 KB

Concrete values:

• Storage needed: 1709 GB = $25.6/month
• Storage write cost: 500,000 writes = $0.00 (1 million free/month)
• Storage read cost: 257,725,329,708 reads = $92,781/month
• Requests cost (package downloads): $0, assuming static access
• Database writes: $0 (50 million free writes/month)
• Database reads: $0 (25 billion free reads/month)

The dominant cost is data access for package downloads. This can be mitigated by passing requests to peers that are mirroring data. Because data is referenced by hash this is a trustless operation (assuming the client verifies each hash). Assuming the majority of package requests are handled in this way the storage read cost should be reduced significantly.

Income can be generated using organization subscriptions. Organizations may pay per seat for the ability to administer packages in an organizational namespace. Automated documentation generation could also be bundled into a subscription based CI service for Noir packages, though manually publishing documentation must also be allowed.

Timeline & Deliverables

Month 1

Implement nrpm publish and Onyx support for user signup, package publishing, package listing. Enable support for statically downloading package tarballs.

Month 2

Implement mocked git retrieval/Nargo compatibility, nrpm install and lockfile management/verification. Implement package yanking and security warnings by authors.

Month 3

Implement synchronization between main Onyx instance and mirrors, read request forwarding.

Month 4

Implement Onyx webserver UI, render package README's, calculate dependent packages. Optimize request routing, do load tests to determine costs as number of packages scale.

Month 5

nrdoc implementation and integration with nrpm. Includes generating docs for the source tree, parsing exported functions using the noir-lang ast, and rendering function and file level descriptions.

Month 6

nrdoc implementation and integration with Onyx. Automatic rendering of documentation for each new package version. Rendered documentation should be available on the package info webpage.

Team

Chance Hudson - former PSE engineer

Start Date

June 23, 2025

Questions