IGhostApplication Interface

Your application contract must implement this interface to receive callbacks from the GhostVault.

Interface Definition

interface IGhostApplication {
    // Called by vault BEFORE commitment recorded. Revert to reject.
    // NOTE: The commitment value is NOT passed to onCommit.
    // Use dataHash or application-level identifiers if you need correlation.
    function onCommit(address user, bytes32 dataHash, bytes calldata data) external;

    // Called by vault AFTER proof verification and BEFORE nullifier recording.
    // Revert cancels entire transaction.
    function onReveal(address recipient, bytes32 dataHash, bytes calldata data) external;

    // Must match your off-chain dataHash computation exactly.
    function computeDataHash(bytes calldata data) external pure returns (bytes32);

    // Optional: pre-flight check before commit.
    function canCommit(address user, bytes32 dataHash) external view returns (bool);

    // Metadata for registry.
    function applicationInfo() external view returns (string memory name, string memory version);
}

Function Details

onCommit

Called by the vault before the commitment is recorded in the Merkle tree.

function onCommit(address user, bytes32 dataHash, bytes calldata data) external;

Parameter	Description
user	Address that initiated the commit
dataHash	Hash of the application data
data	Raw application data bytes

Use cases:

• Validate the data format
• Lock assets (tokens, NFTs)
• Record off-chain identifiers

If this reverts: The commitment is NOT recorded. Use this to reject invalid commits.

onReveal

Called by the vault after proof verification but before nullifier recording.

function onReveal(address recipient, bytes32 dataHash, bytes calldata data) external;

Parameter	Description
recipient	Address receiving the reveal (specified by revealer)
dataHash	Hash of the application data
data	Raw application data bytes

Use cases:

• Transfer assets to recipient
• Update application state
• Emit events

Critical

If onReveal reverts, the entire transaction reverts and the nullifier is NOT spent. The user can retry. Design this function to succeed for valid inputs.

computeDataHash

Computes the data hash from raw data. Must match your off-chain computation exactly.

function computeDataHash(bytes calldata data) external pure returns (bytes32);

Requirements:

• Must be a pure function
• Must be deterministic
• Must match your off-chain dataHash computation

Example:

function computeDataHash(bytes calldata data) external pure returns (bytes32) {
    return bytes32(uint256(keccak256(data)) % FIELD_SIZE);
}

canCommit

Optional pre-flight check before commit. The vault may call this to check if a commit is allowed.

function canCommit(address user, bytes32 dataHash) external view returns (bool);

Use cases:

• Check user allowlists
• Verify data hash is valid for the application
• Rate limiting

applicationInfo

Returns metadata about the application.

function applicationInfo() external view returns (string memory name, string memory version);

Modifier Pattern

Always use a modifier to ensure only the vault can call your callbacks:

address public immutable vault;

modifier onlyVault() {
    require(msg.sender == vault, "Only vault");
    _;
}

function onCommit(address user, bytes32 dataHash, bytes calldata data) external onlyVault {
    // ...
}

function onReveal(address recipient, bytes32 dataHash, bytes calldata data) external onlyVault {
    // ...
}

Next Steps

• Safety Rules - Critical rules for your implementation
• One-Time Access Token Tutorial - Complete example