The Interfold Contract

This page describes the public API of the Interfold contract (Interfold.sol) for application builders. It covers the request function and its parameters, where inputs go, the two output functions, the read functions, the events, and the custom errors. At the end of the page, you can call the contract directly or read the calls that the SDK makes for you. For the stages and their deadlines in order, see E3 lifecycle.

What the contract does

The Interfold contract records each E3 and moves it through its stages. It does these tasks:

• Accepts E3 requests and takes the fee.
• Asks the CiphernodeRegistry to select a committee.
• Records the committee public key commitment when the registry reports it.
• Accepts the ciphertext output after the E3 program and the protocol verifier accept the proof.
• Accepts the plaintext output after the decryption verifier accepts the proof.
• Pays rewards on success and sends failed E3s to refund settlement.

The Interfold contract does not accept inputs. Each E3 program accepts its own inputs in its publishInput function. See Input publication.

1. requestThe requester pays the fee. Interfold asks the registry for a committee.
3. publishInputData providers send encrypted inputs to the E3 program, not to Interfold.
5. publishCiphertextOutputA server sends a proof-backed reference to the encrypted result.
7. publishPlaintextOutputCiphernodes send the decrypted result and the decryption proof.

Request an E3

The request function takes one struct and returns the new E3 ID and the stored E3 record.

function request(
  E3RequestParams calldata requestParams
) external returns (uint256 e3Id, E3 memory e3);

request pulls the fee with transferFrom. Before you call it, approve the Interfold contract to spend the quoted fee in the fee token. For the fee formula and the refund rules, see Request an E3.

Request parameters

E3RequestParams is defined in interfaces/IInterfold.sol.

The configuration IDs for each parameter set are constants in lib/ActiveCryptoConfig.sol (INSECURE_CONFIG_ID and SECURE_CONFIG_ID). The SDK fills expectedFeeToken, expectedCryptoConfigId, and maxFee for you. See SDK.

What request checks

request runs these checks in order. The first check that fails reverts the call.

1. Requests are not paused (RequestsPaused). A new deployment starts with requests paused.
2. The registry, bonding registry, slashing manager, refund manager, and node release registry form one consistent set (DependencyConfigurationMismatch).
3. The current fee token is on the allow-list (FeeTokenNotAllowed).
4. The E3 program is registered (E3ProgramNotAllowed).
5. The quote succeeds. The quote checks the input window, the total duration, the parameter set, and the committee size.
6. The current fee token, the configuration ID for paramSet, and the quote agree with expectedFeeToken, expectedCryptoConfigId, and maxFee.
7. The E3 program validate call returns an encryption scheme ID. Interfold must have a decryption verifier and a public key verifier for that scheme (InvalidEncryptionScheme).
8. The fee transfer delivers the exact amount (AssetTransferMismatch).
9. The registry accepts the committee request. The registry reverts when fewer than N eligible ciphernodes (InsufficientCiphernodes) or fewer than N bond owners (InsufficientBondOwners) are available.

The total duration check uses the worst case. Interfold takes the later of the input window end and the committee setup time, then adds the compute window and the decryption window. The committee setup time is the randomness timeout, plus the sortition submission window, plus the DKG window. The total must not be more than maxDuration (InvalidDuration).

What request stores and emits

A successful request does these things:

• Assigns the next E3 ID. The first ID is the Interfold address shifted left by 96 bits, so E3 IDs are large numbers.
• Freezes the registry, bonding registry, refund manager, slashing manager, and timeout configuration for this E3.
• Stores the service fee as escrow. It credits the flat randomness fee to the treasury.
• Sets the stage to Requested.
• Emits E3Requested(e3Id, e3, cryptoConfigId) and E3StageChanged(e3Id, None, Requested).

The E3 record

getE3(e3Id) returns the E3 struct from interfaces/IE3.sol.

Input publication

Inputs go to the E3 program. IE3Program defines the entry point:

function publishInput(uint256 e3Id, bytes memory data) external;

The E3 program decides the encoding of data, the checks, and the storage. Interfold does not check the input window for inputs. Interfold enforces the window only on the output: it rejects a ciphertext output before inputWindow[1]. The default template and CRISP use different input paths.

The template program does not prove that the ciphertext matches its commitment. A comment in MyProgram.sol states that a production program must verify this binding. For the program side, see Program contract.

Publish the ciphertext output

After the compute provider runs, a server publishes a reference to the encrypted result. The ciphertext bytes stay off Ethereum, on a data availability layer.

function publishCiphertextOutput(uint256 e3Id, bytes calldata encodedOutputReference) external;

encodedOutputReference is the ABI encoding of one CiphertextOutputReference tuple:

Any account can call the function. The call succeeds only when all of these conditions are true:

• The E3 is in KeyPublished.
• The current time is at or after inputWindow[1] (InputDeadlineNotReached).
• The current time is at or before the compute deadline (CommitteeDutiesCompleted).
• No output exists yet (CiphertextOutputAlreadyPublished), and contentHash is not zero.
• The committee still has enough active members (ThresholdNotMet from the registry).
• e3Program.verifyDataAvailability(contentHash, availabilityProof) returns a receipt for the same contentHash.
• The request-time protocol ciphertext verifier and e3Program.verify both accept the proof.

A receipt for a different hash, or a proof that a verifier rejects, reverts with InvalidOutput. The E3 program can also revert with its own error. On success, the E3 moves to CiphertextReady and the decryption deadline starts. The contract emits CiphertextOutputReferencePublished(e3Id, contentHash, ciphertextCommitment, availabilityBlock, availabilityLeafIndex) and E3StageChanged.

Publish the plaintext output

The committee decrypts the output, and one ciphernode publishes the result and the proof.

function publishPlaintextOutput(
  uint256 e3Id,
  bytes calldata plaintextOutput,
  bytes calldata proof
) external returns (bool success);

The call succeeds only when the E3 is in CiphertextReady and the decryption deadline has not passed. The proof must not be empty (ProofRequired). The committee must still be viable, and the decryption verifier must accept the proof.

On success, the E3 moves to Complete. The contract credits the treasury share and the committee rewards. It emits RewardsDistributed, PlaintextOutputPublished(e3Id, plaintextOutput, proof), and E3StageChanged. Rewards are pull payments. Each recipient calls claimReward(e3Id) or claimRewards(e3Ids).

Failure functions

These functions handle an E3 that does not finish. For the rules and the refund amounts, see Request an E3.

During markFailedGracePeriod after a deadline, only the requester, the contract owner, or an active committee member can call markE3Failed (MarkE3FailedInGracePeriod).

Read functions

These view functions are the ones that applications use most.

Events

The Interfold contract emits these events for the E3 lifecycle.

IInterfold also declares InputPublished and CiphertextOutputPublished. The Interfold contract does not emit them. E3 programs emit their own input events, and new outputs use CiphertextOutputReferencePublished.

The CiphernodeRegistry emits the committee events. Applications use these most:

Custom errors

These errors are the ones that an application sees most. All are declared in IInterfold, except the registry errors.

Security considerations

• Committee size. The committee enum fixes N, H, and T. You cannot choose other thresholds. A larger committee costs more because the quote grows with N and H.
• Input validation. Interfold does not see inputs. Your E3 program must check who can submit, when, and what. It must also bind each ciphertext to its commitment.
• Output verification. Interfold accepts a ciphertext output only if your program's verify accepts the proof. A weak verify gives a weak guarantee. Your E3s also depend on the trust model of your compute provider.
• Event finality. A reorganization can remove an event that you already read. Wait for enough confirmations before you act on an event that moves funds or ends a process.

Next steps