diff --git a/in-progress/NNNN-off-chain-contract-registry.md b/in-progress/NNNN-off-chain-contract-registry.md new file mode 100644 index 0000000..1cb9ad2 --- /dev/null +++ b/in-progress/NNNN-off-chain-contract-registry.md @@ -0,0 +1,44 @@ +| | | +| -------------------- | --------------------------- | +| Issue | Off-chain contract registry | +| Owners | @spalladino | +| Approvers | | +| Target Approval Date | | + +## Executive Summary + +Since private contracts are not broadcasted on-chain, they need to be registered in a PXE before they can be executed. We expect this to be typically done by the dapp in context, but for composability's sake and ease of development, especially during devnet, we could make things easier by keeping a canonical off-chain registry of contracts. + +## Introduction + +When executing a private function on a contract in the PXE, we require that the corresponding contract instance and artifact to have been registered in advance. + +We can extend the PXE to fall back to requesting the instance and artifact to an external provider, and registering them on the fly during a simulation. Since the contract address acts as a commitment to the instance and artifact, the PXE can validate the downloaded artifact against the address itself by recomputing the class id and instance address. + +## Interface + +We split the interface into two: one for uploading and registering instances and artifacts, and another for querying. This allows us to implement a trusted registry with just the query interface first, to make it quickly available to devs, and manage the registration centrally until we implement the more complex uploading API. + +### Querying + +#### GET `/contracts/{address}.json` + +Returns the JSON-serialized contract instance for the given address, which includes the class identifier. + +#### GET `/artifacts/{class_id}.json` + +Returns the JSON-serialized contract artifact (as generated by Nargo) for the given class identifier. + +### Uploading + +#### POST `/contracts/{address}.json` + +Uploads a JSON-serialized contract instance for the given address. The server must verify that the instance hashes to the given address. + +#### POST `/artifacts/{class_id}.json` + +Uploads a JSON-serialized artifact for the given class id. The server must verify that the artifact hashes to the given class id. + +## Implementation Notes + +The flat querying API means we can implement the registry in a plain file storage service like S3.