Skip to content

Fetching Secrets

This article explains how to fetch secrets from MPC smart contracts.

To fetch secrets, you must first submit secret inputs to the smart contract. Learn how to submit secret inputs here.

  • First, we explain the process of fetching secrets from both the user's and the MPC nodes' perspective. This is generic for all languages. We include an example of fetching a secret through your terminal with Partisia CLI.
  • Second, we show how you can fetch secrets from your own application using TypeScript and Java.

Fetching Secrets from the Nodes

In an MPC contract, information about secrets is stored in the contract's MPC state. The secret itself is secret shared and distributed to the MPC nodes. You can think of this storage as a structured database table, where each row represents a secret variable along with relevant metadata, such as the owner of the secret and other contract created attributes. Each secret is assigned a unique ID, which acts as a counter, based on the order agreed upon by the MPC nodes. This ensures a consistent and structured way of referencing secrets. For example, the table below illustrates how secrets are organized:

ID Transaction Owner Metadata ...
3 transactionId3 owner3 metadata3 ...
2 transactionId2 owner2 metadata2 ...
1 transactionId1 owner1 metadata1 ...

The owner of a secret variable can fetch the secret from the MPC nodes allocated to the MPC contract using an HTTP-request. The owner is typically the sender of the secret, but ownership can also be transferred with a ZK state change in the MPC contract.

To fetch a secret, the owner initiates a fetch request, specifying the corresponding secret variable, to all MPC nodes. Subsequently, each node transmits its share of the secret back to the owner. When the owner has received sufficient shares, the secret can be reconstructed. The fetch request is sent directly to the nodes (off-chain) using an HTTP-request.

./graphics/fetch-secret-shares.svg

In more detail, the owner (Sender) of the secret must;

  1. Sign a hash of a transaction request to get the secret with some secret variable id.
  2. Send the signed hash and the request to the nodes off-chain.
  3. After receiving shares off-chain from the nodes, combine the secret shares to reconstruct the secret.

In turn, the MPC nodes:

  1. Use the sender's signature to verify that the sender owns the secret with the secret variable ID they are requesting.
  2. When verified, send their secret share of the requested secret to the sender.

Example in the terminal

You can fetch secrets in your terminal. In this example, we will see how you can fetch a secret input to an Average Salary MPC smart contract.

Sending a secret input with CLI is similar to sending a public action transaction.

Requirements

  • A local Partisia Platform deployment
  • Deployed Average Salary MPC smart contract
  • Sent a secret to the contract with your private key.

To fetch your secret input write the following command, specifying which contract to fetch the secret from, the type of the secret (here: i32) and its secret ID (here: 1). Additionally, you must provide a path to your private key to prove to the nodes that you are the owner of the secret:

cargo pbc contract secret show averageSalaryAddress 1 i32 --privatekey path/to/private/key.txt

This will output 123456.

Tip

You can find the secret ID under "ZK data" in the Browser frontend at http://docker:8300/contracts/averageSalaryAddress. This also shows you all interactions with the contract, the contract state and the ZK state.

Fetching secrets in your application

It is possible to fetch secrets programmatically in Java, TypeScript and in your terminal using Partisia CLI.

The Partisia Platform provides a library to interact with the nodes and the blockchain. This contains a Java and a Typescrypt zk-client which facilitates communication with the MPC nodes (HTTP-request to the MPC node endpoints) and the chain (HTTP-request to the reader node endpoint).

The Java and Typescript ZkClient can fetch a secret exclusively on behalf of the secret's owner. In many cases, the owner is the sender of the secret.

To use the following code examples, update the following fields with appropriate values:

  • privateKey – Use your own private key.
  • averageSalaryAddress – Provide the address of a deployed contract. Read more about deploying contracts here.
  • blockchainUrl – We provide http://docker:9432 as the blockchain URL. You can use this if you have a running local deployment, as described here.
  • secretVarId – The secret variable ID acts as a counter. In this example, the ID should be set to 1.

Using TypeScript

The following example fetches a secret from an average Salary MPC smart contract, using the Typescript zk-client.

The owner of a secret must provide their senderAuthentication (key pair) to sign the fetch request of that specific secret. This allows the nodes to verify that the sender is the owner of the secret.

In addition, you must provide the secret's variable id.

Fetching a secret in TypeScript 
async function averageSalaryExampleOffChain() {
    // Blockchain address of the contract and the reader node URL
    const averageSalaryAddress = "000000000000000000000000000000000000000001";
    const blockchainUrl = "http://docker:9432";

    // Blockchain- and ZK-Client
    const client = new Client(blockchainUrl, 0);
    const realZkClient = await RealZkClient.create(averageSalaryAddress, client);

    // Private key for authentication
    const privateKey = "myprivatekey";
    const signatureProvider = new SignatureProviderKeyPair(
    CryptoUtils.privateKeyToKeypair(privateKey)
    );

    // Fetch a secret with secret variable ID 1
    const secretVarId = 1;
    const reconstructedSecret: CompactBitArray = await realZkClient.fetchSecretVariable(
    signatureProvider,
    secretVarId
    );

    // Deserialize the secret
    const secret = new BitInput(reconstructedSecret.data).readSignedBN(32);
    console.log(secret);
}

Using Java

The following example fetches a secret from an average Salary MPC smart contract, using the Java zk-client.

To fetch a secret, in this case a salary, you must first send the secret. Read how to do it here.

The owner (here: the sender of the secret) of a secret must provide their senderAuthentication (key pair) to sign the fetch request of that specific secret. This allows the nodes to verify that the sender is the owner of the secret.

In addition, you must provide the secret's variable id. In this example where there is only one secret input, the ID is 1.

Fetching a secret in Java 
public static void main(final String[] args) {

    // Address of a deployed average salary contract
    BlockchainAddress averageSalaryAddress =
        BlockchainAddress.fromString("000000000000000000000000000000000000000001");
    // Create a blockchain client. Provide the reader node URL and number of shards.
    BlockchainClient blockchainClient = BlockchainClient.create("http://docker:9432", 0);

    // Create a webclient for communicating with the nodes
    Client client =
        ClientBuilder.newBuilder()
            .connectTimeout(30L, TimeUnit.SECONDS)
            .readTimeout(30L, TimeUnit.SECONDS)
            .build();
    WebClient webClient = new JerseyWebClient(client);

    // Create the zk client with the contract address, a webclient, and a blockchain client.
    RealZkClient zkClient = RealZkClient.create(averageSalaryAddress, webClient, blockchainClient);

    String privateKey = "myprivatekey";
    SenderAuthenticationKeyPair keyPair = SenderAuthenticationKeyPair.fromString(privateKey);
    int secretVarId = 1;

    // Fetch the secret variable by providing the secret var ID and key pair
    CompactBitArray serializedSecret = zkClient.fetchSecretVariable(keyPair, secretVarId);
    // To deserialize, you must specify the type of the secret. Here it is an I32.
    int reconstructedSecret = BitInput.create(serializedSecret.data()).readSignedInt(32);

    System.out.println(reconstructedSecret);
}