Circuit Identifiers

How particular circuit versions are specified

Anywhere within the Sindri API, CLI, or SDKs where a Circuit ID can be provided, the system is capable of accepting either of the following formats.

	Format	Example
Circuit Name	[TEAM/]NAME[:TAG]	sindri/pagerank:v1.0.0
Immutable Circuit ID	UUID	bf175e5c-190b-4438-bd8e-bfa452afbef2

Circuit Name Format

The Circuit Name Format is a human-readable format that is used to specify a particular version of a circuit. It's heavily inspired by the Docker image naming convention, and should feel very familiar to anyone who has used Docker before. The identifier is composed of the following parts:

• TEAM (optional) - The name of the team that owns the circuit. If not provided, the circuit is assumed to be owned by the user or team that is currently authenticated.
• NAME (required) - The name of the circuit project repository.
• TAG (optional) - The tag of the circuit version. If not provided, the latest tag is used as the default.

Below are practical examples demonstrating how to utilize the Circuit Name Format in different contexts.

Examples

Clone a Public Circuit From Another Team

This example uses the sindri clone command to clone the sha256 circuit published by the sindri team into a local directory. Since no tag is provided, the latest tag is used by default. The sha256 circuit repository is public, so you're able to access and clone this repository even if you're not a member of the sindri team.

sindri clone sindri/sha256

Output

[16:36:29.183] INFO: Cloning the circuit "sindri/sha256" into "/sha256".
[16:36:29.743] INFO: Circuit cloned successfully.

Create a Proof for a Public Circuit

The code here uses the TypeScript SDK to create a new proof for the exponentiate circuit published by the sindri team. It explicitly specifies the v1.0.0 tag instead of the default latest. The generated proof proves that $2^8 = 256$.

import sindri from 'sindri';

// Create a proof that 2^8 = 256 using the `exponentiate` circuit.
const proof = await sindri.proveCircuit(
  'sindri/exponentiate:v1.0.0',
  JSON.stringify({ X: '2', E: '8', Y: '256' }),
);

// Log out the proof status.
console.log('Proof Status:', proof.status);

Output

Proof Status: Ready

Clone a Tagged Version of Your Own Circuit

This command clones the v2.1.4 tag of the semaphore circuit published by your own team. Since no explicit team is specified, you must be authenticated as a member of the team that owns the semaphore circuit or you will receive a "Circuit Not Found" error. You'll receive the same error if the v2.1.4 tag does not exist in the semaphore circuit repository.

sindri clone semaphore:v2.1.4

Output

[16:36:56.287] INFO: Cloning the circuit "semaphore:v2.1.4" into "/semaphore".
[16:36:56.828] INFO: Circuit cloned successfully.

Immutable Circuit ID Format

The Immutable Circuit ID Format is a unique identifier that is used to specify a particular version of a circuit. Circuit names and tags provide a convenient way to reference a circuit, but they are less exact than the Immutable Circuit ID. Team names and circuit repository names can both be changed, and the most recent version of a circuit tag can be overwritten, while the Immutable Circuit ID will always refer to the same circuit version. Using the Immutable Circuit ID allows you to "pin" a particular version of a circuit, so that you can be certain the circuit will not change even if the circuit name or tag is updated.

The Immutable Circuit ID is a UUID that is generated by the Sindri platform when a circuit is created, and it is guaranteed to be unique across all circuits and to never change. Whenever a circuit is returned in an API response, the Immutable Circuit ID will always be included as the circuit_id field.

Examples

Find the Circuit ID and Refetch the Circuit

This code uses the TypeScript SDK to fetch the public pagerank circuit published by the sindri team, and extracts the Immutable Circuit ID from the response. It then fetches the same circuit using the Immutable Circuit ID, and verifies that the two circuit IDs are identical.

import sindri from 'sindri';

// Fetch the public Sindri pagerank circuit using the circuit name format.
const circuit = await sindri.getCircuit('sindri/pagerank');
const circuitId = circuit.circuit_id;
console.log('Circuit ID:', circuitId);

// Fetch the public Sindri pagerank circuit using the immutable circuit ID format.
const sameCircuit = await sindri.getCircuit(circuitId);
const sameCircuitId = sameCircuit.circuit_id;
console.log('Circuit IDs are the same?', circuitId === sameCircuitId);

Output

Circuit ID: bf175e5c-190b-4438-bd8e-bfa452afbef2
Circuit IDs are the same? true

Clone an Exact Circuit Version

The example here clones an exact version of a circuit into the exact-circuit directory using the sindri clone command.

sindri clone b8dbba00-191a-44ac-ac5d-05a5d44d9186 exact-circuit

Output

[17:18:09.626] INFO: Cloning the circuit "b8dbba00-191a-44ac-ac5d-05a5d44d9186" into "/private/tmp/my-project/exact-circuit".
[17:18:11.539] INFO: Circuit cloned successfully.