Skip to main content

Requesting program runs

Once programs are uploaded and users have provided encrypted inputs, program runs can be requested from SPF. This section covers parameter encoding, run submission, and result retrieval using Solidity smart contracts.

Important: Ensure programs are uploaded before requesting runs.

Encoding parameters​

Before submitting a run, parameters must be encoded to match the FHE program’s signature. The Solidity library provides helper functions for each parameter type that handle the encoding internally. For all functions below the underlying data in the ciphertext must be the correct bit width matching the C program signature (8, 16, 32 or 64 bits).

Parameter types​

The following functions create properly encoded parameters for different C types:

Single ciphertext parameter: For a single encrypted input (C type [[clang::encrypted]] (u)intN_t value)

The function signature is

function createCiphertextParameter(SpfCiphertextIdentifier identifier) returns (SpfParameter memory)

Ciphertext array parameter: For an array of encrypted inputs (C type [[clang::encrypted]] (u)intN_t *value)

The function signature is

function createCiphertextArrayParameter(SpfCiphertextIdentifier[] memory identifiers) returns (SpfParameter memory)

Plaintext parameter: For a plaintext input (C type (u)intN_t value)

The function signature is

function createPlaintextParameter(uint8 bitWidth, int128 value) returns (SpfParameter memory)

Plaintext array parameter: For an array of plaintext inputs (C type (u)intN_t *value)

The function signature is

function createPlaintextArrayParameter(uint8 bitWidth, int128[] memory values) returns (SpfParameter memory)

Output ciphertext array parameter: For an array of encrypted outputs (C type [[clang::encrypted]] (u)intN_t *value)

The function signatures are

function createOutputCiphertextParameter(uint8 bitWidth) returns (SpfParameter memory)

or

function createOutputCiphertextArrayParameter(uint8 bitWidth, uint8 numElements) returns (SpfParameter memory)

For array outputs, numElements specifies the number of ciphertexts in the output array and is required to derive output handles later.

Submitting a program run​

To submit a run request to execute an FHE program, use the requestRunAsContract() function:

function requestRunAsContract(SpfLibrary spfLibrary, SpfProgram program, SpfParameter[] memory params) returns (SpfRunHandle)

The function submits the computation request to SPF and returns a unique run handle. This handle is used to derive output ciphertext identifiers.

Parameters:

  • spfLibrary: SpfLibrary - The library identifier from program upload
  • program: SpfProgram - The program entry point name (function name in C code)
  • params: SpfParameter[] memory - Array of encoded parameters in order matching the C function signature

Returns: SpfRunHandle - The run handle for deriving output ciphertexts

Retrieving output ciphertexts​

After a program run completes, output ciphertexts IDs can be calculated using the getOutputHandle() function based on the run handle and output index.

function getOutputHandle(SpfRunHandle runHandle, uint8 index) returns (SpfParameter memory)

Parameters:

  • runHandle: SpfRunHandle - The run handle from requestRunAsContract()
  • index: uint8 - The index of the output ciphertext (0-255)

Returns: SpfParameter memory - The result ciphertext as an SpfParameter, which can be used directly as input to another program or converted to a raw ciphertext identifier for decryption

Determining the output index​

The output index corresponds to the position in the flattened array of all output ciphertexts from all output parameters.

For example, if a program has these parameters:

void example(
  int16_t* encrypted_inputs,  // Input (ignored for index)
  uint16_t num_inputs,         // Plaintext (ignored for index)
  int16_t* first_output,       // Output array with 2 elements
  uint8_t* second_output       // Output array with 1 element
)

The Solidity parameters would be:

SpfParameter[] memory parameters = new SpfParameter[](4);
parameters[0] = Spf.createCiphertextArrayParameter([...]);
parameters[1] = Spf.createPlaintextParameter(16, 5);
parameters[2] = Spf.createOutputCiphertextArrayParameter(16, 2); // Indices 0, 1
parameters[3] = Spf.createOutputCiphertextArrayParameter(8, 1);  // Index 2

Output indices:

  • Index 0: first element in first_output
  • Index 1: second element in first_output
  • Index 2: second_output

Built-in trivial ciphertexts​

As a convenience, the SPF library provides access to known encryptions of 0 and 1 using the createTrivialZeroCiphertextParameter(uint8 bitWidth) and createTrivialOneCiphertextParameter(uint8 bitWidth) functions.

Verifying ciphertext access​

To ensure that a program will run (which requires all the ciphertexts inputs are valid and available to the program), applications should verify ciphertext access before submitting a run request. However, smart contracts cannot directly verify the status of ciphertexts stored in the SPF service.

To solve this problem, the SPF service provides off-chain access verification functionality that can be used to obtain a signature confirming the SPF has access to specific ciphertexts with the correct permissions. Smart contracts can then verify these signatures on-chain before executing the program run, ensuring that their requests will execute successfully.

See the tooling for acquiring these signatures and verifying access control for more details.