Exemplary Use-Cases

1. Encrypted arguments

Encrypted arguments are independent of any particular call descriptor and can be reused.

Upon (off-chain) encryption (initialization) a hash of the (plain) arguments is generated accompanying the encrypted arguments to allow later verification.

struct EncryptedHashedArguments {
    /**
     * Commitment to the plaintext argument payload.
     * The target contract should check keccak256(argsPlain) == argsHash.
     */
    bytes32 argsHash;

    /**
     * Identifier of the public key used for encryption (e.g. keccak256 of key material).
     */
    bytes32 publicKeyId;

    /**
     * Ciphertext of abi.encode(ArgsDescriptor), encrypted under publicKeyId.
     */
    bytes ciphertext;
}

struct ArgsDescriptor {
    /**
     * List of addresses allowed to request decryption.
     * If empty, any requester is allowed. This is enforced off-chain by the oracle operator.
     */
    address[] eligibleCaller;

    /**
     * Plain argument payload, may be abi.encode(args...).
     */
    bytes argsPlain;
}

bytes32 argsHash = keccak256(argsDescriptor.argsPlain);
bytes   ciphertext = ENC_publicKeyId(abi.encode(argsDescriptor));

2. Call descriptor

A call descriptor defines:

• which contract and function will be called, and
• any validity constraint (e.g. expiry block).

struct CallDescriptor {
    /**
     * Contract that will be called by the oracle.
     */
    address targetContract;

    /**
     * Function that will be called by the oracle.
     * 4-byte function selector for the targetContract whose signature MUST be (uint256, bytes).
     */
    bytes4 selector;

    /**
     * Optional expiry (block number). 0 means "no explicit expiry".
     */
    uint256 validUntilBlock;
}

struct EncryptedCallDescriptor {
    /**
     * Identifier of the public key used for encryption.
     */
    bytes32 publicKeyId;

    /**
     * Ciphertext of abi.encode(CallDescriptor), encrypted under publicKeyId.
     */
    bytes ciphertext;
}

3. Oracle interface

The oracle exposes a request/fulfill pattern. Requests are cheap and do not require on-chain decryption; fulfillment is called by an off-chain operator after decryption.

interface ICallDecryptionOracle {
    /// Raised when a request with encrypted call descriptor + encrypted args is registered.
    event EncryptedCallRequested(
        uint256 indexed requestId,
        address indexed requester,
        bytes32 callPublicKeyId,
        bytes   callCiphertext,
        bytes32 argsPublicKeyId,
        bytes   argsCiphertext,
        bytes32 argsHash
    );

    /// Raised when a request with plain call descriptor + encrypted args is registered.
    event CallRequested(
        uint256 indexed requestId,
        address indexed requester,
        address   targetContract,
        bytes4    selector,
        uint256   validUntilBlock,
        bytes32   argsPublicKeyId,
        bytes     argsCiphertext,
        bytes32   argsHash
    );

    /// Raised when an execution attempt has been fulfilled by the oracle operator.
    event CallFulfilled(
        uint256 indexed requestId,
        bool    success,
        bytes   returnData
    );

    /**
     * @notice Request execution with encrypted call descriptor + encrypted arguments.
     *
     * @dev MUST:
     * - register a unique requestId,
     * - store (requestId → requester, argsHash, and auxiliary metadata),
     * - emit EncryptedCallRequested.
     */
    function requestEncryptedCall(
        EncryptedCallDescriptor   calldata encCall,
        EncryptedHashedArguments  calldata encArgs
    ) external returns (uint256 requestId);

    /**
     * @notice Request execution with plain call descriptor + encrypted arguments.
     *
     * @dev MUST:
     * - require encArgs.argsHash to be consistent with any application-level commitments,
     * - register a unique requestId and store callDescriptor data + requester,
     * - emit CallRequested.
     */
    function requestCall(
        CallDescriptor            calldata callDescriptor,
        EncryptedHashedArguments  calldata encArgs,
        bytes                     calldata secondFactor
    ) external returns (uint256 requestId);

    /**
     * @notice Fulfill an encrypted-call request after off-chain decryption.
     *
     * @param requestId      The id obtained from requestEncryptedCall.
     * @param callDescriptor The decrypted CallDescriptor.
     * @param argsPlain      The decrypted argument payload bytes.
     *
     * @dev MUST:
     * - verify that requestId exists and was created with requestEncryptedCall,
     * - verify callDescriptor.validUntilBlock is zero or >= current block.number,
     * - verify that keccak256(argsPlain) equals the stored argsHash,
     * - perform low-level call:
     *     callDescriptor.targetContract.call(
     *         abi.encodeWithSelector(callDescriptor.selector, requestId, argsPlain)
     *     )
     * - emit CallFulfilled(requestId, success, returnData),
     * - clean up stored state for this requestId.
     */
    function fulfillEncryptedCall(
        uint256          requestId,
        CallDescriptor   calldata callDescriptor,
        bytes            calldata argsPlain
    ) external;

    /**
     * @notice Fulfill a plain-call request after off-chain decryption of the arguments.
     *
     * @param requestId The id obtained from requestCall.
     * @param argsPlain The decrypted argument payload bytes.
     *
     * @dev MUST:
     * - verify that requestId exists and was created with requestCall,
     * - load stored CallDescriptor from state,
     * - verify callDescriptor.validUntilBlock is zero or >= current block.number,
     * - verify that keccak256(argsPlain) equals the stored argsHash,
     * - perform low-level call:
     *     callDescriptor.targetContract.call(
     *         abi.encodeWithSelector(callDescriptor.selector, requestId, argsPlain)
     *     )
     * - emit CallFulfilled(requestId, success, returnData),
     * - clean up stored state for this requestId.
     */
    function fulfillCall(
        uint256          requestId,
        bytes            calldata argsPlain
    ) external;
}

Note: The call decryption oracle interface does not standardize the exact storage layout of pending requests or the internal access control for fulfill* (e.g. onlyOracle). Implementations MUST ensure that only the intended oracle operator can call the fulfill* functions.

4. Target contract

A common pattern is that the target contract

1. In an initialization phase, receives and stores an encrypted argument encArg together with its hash argsHash, where argsHash is the hash of the plaintext argument payload.
2. In the execution phase, the caller issues a request to the call decryption oracle, obtains the requestId returned by requestCall / requestEncryptedCall, and passes this requestId along with argsHash to the call target (may be the same contract) in the same transaction. The call target then receives the decrypted argument payload argsPlain (under a callback selector) from the call decryption oracle, with the corresponding requestId and recomputes the hash and compares it to the stored value.
3. The call target can the procees with the business logic operating on the decrypted (and verified) arguments.

For example, the producer of EncryptedHashedArguments may choose

bytes memory argsPlain = abi.encode(amount, beneficiary);
bytes32 argsHash = keccak256(argsPlain);

The target (or router) contract can then do:

mapping(uint256 => bytes32) public argsHashByRequestId;

function registerArguments(uint256 requestId, bytes32 argsHash) external {
    // In the same transaction as the request, store the commitment for this requestId.
    argsHashByRequestId[requestId] = argsHash;
}

/**
 * @dev Target selector: Called by the Call Decryption Oracle with decrypted arguments.
 * The oracle calls this function with signature
 *    callback(uint256 requestId, bytes argsPlain)
 * where requestId is the technical correlation id assigned by the oracle.
 */
function executeWithVerification(
    uint256 requestId,
    bytes   calldata argsPlain
) external {
    // Lookup the pre-committed hash from the init phase.
    bytes32 stored = argsHashByRequestId[requestId];
    require(stored != bytes32(0), "Unknown requestId");

    // Recompute the hash from the received bytes.
    bytes32 computed = keccak256(argsPlain);
    require(computed == stored, "Encrypted args mismatch");

    /**
     * Optional: decode argsPlain to use it, e.g.
     *   (uint256 amount, address beneficiary) = abi.decode(argsPlain, (uint256, address));
     * and route to business logic.
     */
}

In this pattern:

• argsHash is the hash commit of argsPlain created upon off-chain argument construction.
• requestId is the technical identifier assigned by the Call Decryption Oracle when the request is issued. It is useful for correlation, logging and mapping inside routers, but is not required for the hash check.
• The argsPlain field passed to fulfill* is the exact byte payload used to compute argsHash. The callback (target or router) decodes argsPlain to recover the business arguments.
• A router/adapter contract can implement the executeWithVerification(uint256 requestId, bytes argsPlain) callback, perform the verification and decoding, and then call an already deployed target contract with its original typed function signature.

Implementations SHOULD register the (requestId, argsHash) mapping in the same transaction that issues the request to the oracle, to avoid any race where a very fast oracle operator could attempt to fulfill a request before the mapping is written on-chain. Even if the mapping is missing, the callback pattern above will cause the fulfillment to revert (due to Unknown requestId); however, registering in the same transaction provides deterministic behaviour.

Fees

Implementations MAY charge fees in ETH or ERC-20 tokens as part of their specific deployment.

Oracle trust

The on-chain contract cannot verify correctness of decryption; it can only check that keccak256(argsPlain) == argsHash. Parties must trust the oracle operator (or design an incentive/penalty mechanism) to decrypt correctly and call fulfill* faithfully.

Replay

Implementations SHOULD mitigate replay by:

• using validUntilBlock in CallDescriptor, and/or
• including nonces or sequence numbers in higher-level protocols.

Access control

Access control is an application-level concern. A common pattern is to embed an access-control list such as address[] eligibleCaller inside the encrypted payload (in ArgsDescriptor) and have the off-chain oracle operator enforce that the original requester is contained in that list (unless the list is empty, meaning “any requester”). The standard does not prescribe a particular access-control mechanism beyond this guidance.

Traceability and non-mixing

The call decryption oracle is not intended to act as a mixer or general-purpose anonymization service for payments or calls. Its purpose is to defer the disclosure of arguments (and optionally the call descriptor) until fulfillment.

Implementations SHOULD preserve the ability for off-chain indexers and observers to correlate CallFulfilled events with the corresponding CallRequested / EncryptedCallRequested events, for example by strictly adhering to the requestId linkage defined in the call decryption oracle interface.

Once a request is fulfilled, an observer can always reconstruct which requester initiated the request and which call and arguments were eventually used. Protocols that deliberately try to break this correlation or to hide value flows are out of scope of the call decryption oracle interface.