Solidity API

IBeaconBlockHistory

IBeaconBlockHistory provides a way to verify beacon block roots as well as execution block hashes

File: interfaces/IBeaconBlockHistory.sol

UPGRADE_BLOCK

function UPGRADE_BLOCK() external view returns (uint256 blockNum)

PrecomittedBlock

event PrecomittedBlock(uint256 blockNum, bytes32 blockHash)

ImportBlockSummary

event ImportBlockSummary(uint256 slot, bytes32 summary)

verifyBeaconBlockRoot

function verifyBeaconBlockRoot(bytes proof) external view returns (bytes32 blockRoot)

verifies a beacon block root

Parameters

NameTypeDescription
proofbytesthe proof of the beacon blcok

Return Values

NameTypeDescription
blockRootbytes32the BeaconBlock root

getBlockSummary

function getBlockSummary(uint256 slot) external view returns (bytes32 result)

gets the cached block summary for the given slot (if it exists)

Parameters

NameTypeDescription
slotuint256the slot number to query

Return Values

NameTypeDescription
resultbytes32the cached block summary (or bytes32(0) if it is not cached)

IBlockHistoryBase

IBlockHistory provides a way to verify a blockhash

File: interfaces/IBlockHistory.sol

validBlockHash

function validBlockHash(bytes32 hash, uint256 num, bytes proof) external view returns (bool)

Determine if the given hash corresponds to the given block

Parameters

NameTypeDescription
hashbytes32the hash if the block in question
numuint256the number of the block in question
proofbytesany witness data required to prove the block hash is correct (such as a Merkle or SNARK proof)

Return Values

NameTypeDescription
0boolboolean indicating if the block hash can be verified correct

IBlockHistoryV0

File: interfaces/IBlockHistory.sol

ImportMerkleRoot

event ImportMerkleRoot(uint256 index, bytes32 merkleRoot)

IBlockHistoryV1

File: interfaces/IBlockHistory.sol

ImportMerkleRoot

event ImportMerkleRoot(uint256 index, bytes32 merkleRoot, bytes32 auxiliaryRoot)

commitRecent

function commitRecent(uint256 blockNum) external

IBlockHistory

File: interfaces/IBlockHistory.sol

IProxyBeaconBlockHistory

IProxyBeaconBlockHistory provides a way to verify beacon block roots as well as execution block hashes on L2s

File: interfaces/IProxyBeaconBlockHistory.sol

commitCurrentL1BlockHash

function commitCurrentL1BlockHash() external

IBlockHashMessenger

File: interfaces/IBlockHashMessenger.sol

sendBlockHash

function sendBlockHash(address destination, bytes params, uint256 number, bytes32 blockHash, bytes proof) external payable

IOptimismNativeBlockHistory

File: interfaces/IOptimismNativeBlockHistory.sol

OutputRootProof

struct OutputRootProof {
bytes32 version;
bytes32 stateRoot;
bytes32 messagePasserStorageRoot;
bytes32 latestBlockhash;
}

proxyMultiStorageSlotProver

function proxyMultiStorageSlotProver() external view returns (address)

l2OutputOracle

function l2OutputOracle() external view returns (address)

OUTPUT_ROOTS_BASE_SLOT

function OUTPUT_ROOTS_BASE_SLOT() external view returns (bytes32)

FINALIZATION_PERIOD_SECONDS

function FINALIZATION_PERIOD_SECONDS() external view returns (uint256)

importCheckpointBlockFromL1

function importCheckpointBlockFromL1(bytes proof, uint256 index, uint256 l1BlockNumber, struct IOptimismNativeBlockHistory.OutputRootProof outputRootProof) external

IProxyBlockHistory

IBlockHistory provides a way to verify a blockhash

File: interfaces/IProxyBlockHistory.sol

TrustedBlockHash

event TrustedBlockHash(uint256 number, bytes32 blockHash)

importTrustedHash

function importTrustedHash(uint256 number, bytes32 hash) external

Import a trusted block hash from the messenger

Parameters

NameTypeDescription
numberuint256the block number to import
hashbytes32the block hash

BirthCertificateVerifier

Defines internal functions and modifiers for querying and verifying accounts' birth certificates.

File: BirthCertificateVerifier.sol

reliquary

contract IReliquary reliquary

constructor

constructor(contract IReliquary _reliquary) public

getBirthCertificate

function getBirthCertificate(address account) internal view returns (uint48, uint64)

Queries the Reliquary for a birth certificate. Reverts if it does not exist. Returns the block number and timestamp of account creation.

Parameters

NameTypeDescription
accountaddressthe account to query

requireOlderThan

function requireOlderThan(address account, uint256 age) internal view

Reverts if the account has not proven its age is at least the provided value.

Parameters

NameTypeDescription
accountaddressthe account to query
ageuint256the age (in seconds)

requireOlderThanBlocks

function requireOlderThanBlocks(address account, uint256 age) internal view

Reverts if the account has not proven its age is at least the provided value.

Parameters

NameTypeDescription
accountaddressthe account to query
ageuint256the age (in blocks)

requireBornBefore

function requireBornBefore(address account, uint256 timestamp) internal view

Reverts if the account has not proven it was before the given time.

Parameters

NameTypeDescription
accountaddressthe account to query
timestampuint256the cutoff timestamp (in seconds)

requireBornBeforeBlock

function requireBornBeforeBlock(address account, uint256 blockNum) internal view

Reverts if the account has not proven it was before the given block number

Parameters

NameTypeDescription
accountaddressthe account to query
blockNumuint256the cutoff block number

onlyOlderThan

modifier onlyOlderThan(uint256 age)

Modifier version of requireOlderThan(msg.sender, age)

Parameters

NameTypeDescription
ageuint256the age (in seconds)

onlyOlderThanBlocks

modifier onlyOlderThanBlocks(uint256 age)

Modifier version of requireOlderThanBlocks(msg.sender, age)

Parameters

NameTypeDescription
ageuint256the age (in blocks)

onlyBornBefore

modifier onlyBornBefore(uint256 timestamp)

Modifier version of requireBornBefore(msg.sender, timestamp)

Parameters

NameTypeDescription
timestampuint256the cutoff timestamp (in seconds)

onlyBornBeforeBlock

modifier onlyBornBeforeBlock(uint256 blockNum)

Modifier version of requireBornBeforeBlock(msg.sender, blockNum)

Parameters

NameTypeDescription
blockNumuint256the cutoff block number

RelicReceiver

File: RelicReceiver.sol

ephemeralFacts

contract IEphemeralFacts ephemeralFacts

constructor

constructor(contract IEphemeralFacts _ephemeralFacts) internal

receiveStorageSlotFact

function receiveStorageSlotFact(address initiator, address account, bytes32 slot, uint256 blockNum, bytes32 value) internal virtual

Handler for receiving ephemeral storage slot facts.

By default, handling storage facts is unimplemented and will revert. Subcontracts should override this function if desired.

Parameters

NameTypeDescription
initiatoraddressthe address which initiated the fact proving
accountaddressthe account for the storage slot
slotbytes32the slot index
blockNumuint256the block number of the fact
valuebytes32the value contained in the slot

receiveBirthCertificateFact

function receiveBirthCertificateFact(address initiator, address account, uint256 blockNum, uint256 timestamp) internal virtual

Handler for receiving ephemeral birth certificate facts.

By default, handling birth certificates is unimplemented and will revert. Subcontracts should override this function if desired.

Parameters

NameTypeDescription
initiatoraddressthe address which initiated the fact proving
accountaddressthe account for the storage slot
blockNumuint256the block number of the birth certificate
timestampuint256the timestamp of the birth certificate

receiveLogFact

function receiveLogFact(address initiator, address account, uint256 blockNum, uint256 txIdx, uint256 logIdx, struct CoreTypes.LogData log) internal virtual

Handler for receiving ephemeral log facts.

By default, handling log facts is unimplemented and will revert. Subcontracts should override this function if desired.

Parameters

NameTypeDescription
initiatoraddressthe address which initiated the fact proving
accountaddressthe account which emitted the log
blockNumuint256the block number of the log
txIdxuint256the index of the transaction in the block
logIdxuint256the index of the log in the transaction
logstruct CoreTypes.LogDatathe log data

receiveBlockHeaderFact

function receiveBlockHeaderFact(address initiator, uint256 blockNum, struct CoreTypes.BlockHeaderData header) internal virtual

Handler for receiving block header facts.

By default, handling block header facts is unimplemented and will revert. Subcontracts should override this function if desired.

Parameters

NameTypeDescription
initiatoraddressthe address which initiated the fact proving
blockNumuint256the block number of the log
headerstruct CoreTypes.BlockHeaderDatathe block header data

receiveFact

function receiveFact(address initiator, struct Fact fact, bytes data) external

receives an ephemeral fact from Relic

Parameters

NameTypeDescription
initiatoraddressthe account which initiated the fact proving
factstruct Factthe proven fact information
databytesextra data passed from the initiator - this contract requires it to be the fact signature data, so that we can identify the fact type and parse the fact parameters.

IEphemeralFacts

File: interfaces/IEphemeralFacts.sol

ReceiverContext

struct ReceiverContext {
address initiator;
contract IRelicReceiver receiver;
bytes extra;
uint256 gasLimit;
bool requireSuccess;
}

FactDescription

struct FactDescription {
address account;
bytes sigData;
}

FactRequested

event FactRequested(struct IEphemeralFacts.FactDescription desc, struct IEphemeralFacts.ReceiverContext context, uint256 bounty)

ReceiveSuccess

event ReceiveSuccess(contract IRelicReceiver receiver, bytes32 requestId)

ReceiveFailure

event ReceiveFailure(contract IRelicReceiver receiver, bytes32 requestId)

BountyPaid

event BountyPaid(uint256 bounty, bytes32 requestId, address relayer)

proveEphemeral

function proveEphemeral(struct IEphemeralFacts.ReceiverContext context, address prover, bytes proof) external payable

proves a fact ephemerally and provides it to the receiver

Parameters

NameTypeDescription
contextstruct IEphemeralFacts.ReceiverContextthe ReceiverContext for delivering the fact
proveraddressthe prover module to use, must implement IProver
proofbytesthe proof to pass to the prover

batchProveEphemeral

function batchProveEphemeral(struct IEphemeralFacts.ReceiverContext[] contexts, address prover, bytes proof) external payable

proves a batch of facts ephemerally and provides them to the receivers

Parameters

NameTypeDescription
contextsstruct IEphemeralFacts.ReceiverContextthe ReceiverContexts for delivering the facts
proveraddressthe prover module to use, must implement IBatchProver
proofbytesthe proof to pass to the prover

requestFact

function requestFact(address account, bytes sigData, contract IRelicReceiver receiver, bytes data, uint256 gasLimit) external payable

requests a fact to be proven asynchronously and passed to the receiver,

msg.value is added to the bounty for this fact request, incentivizing somebody to prove it

Parameters

NameTypeDescription
accountaddressthe account associated with the fact
sigDatabytesthe fact data which determines the fact signature (class is assumed to be NO_FEE)
receivercontract IRelicReceiverthe contract to receive the fact
databytesthe extra data to pass to the receiver
gasLimituint256the maxmium gas used by the receiver

IRelicReceiver

IRelicReceiver has callbacks to receive ephemeral facts from Relic The Relic SDK provides a RelicReceiver base class which implements IRelicReceiver and simplifies ephemeral fact handling.

File: interfaces/IRelicReceiver.sol

receiveFact

function receiveFact(address initiator, struct Fact fact, bytes data) external

receives an ephemeral fact from Relic

Parameters

NameTypeDescription
initiatoraddressthe account which initiated the fact proving
factstruct Factthe proven fact information
databytesextra data passed from the initiator - this data may come from untrusted parties and thus should be validated

IReliquary

The Reliquary is the heart of Relic. All issuers of Relics and Artifacts must be added to the Reliquary. Queries about Relics and Artifacts should be made to the Reliquary.

File: interfaces/IReliquary.sol

NewProver

event NewProver(address prover, uint64 version)

Issued when a new prover is accepted into the Reliquary

Parameters

NameTypeDescription
proveraddressthe address of the prover contract
versionuint64the identifier that will always be associated with the prover

PendingProverAdded

event PendingProverAdded(address prover, uint64 version, uint64 timestamp)

Issued when a new prover is placed under consideration for acceptance into the Reliquary

Parameters

NameTypeDescription
proveraddressthe address of the prover contract
versionuint64the proposed identifier to always be associated with the prover
timestampuint64the earliest this prover can be brought into the Reliquary

ProverRevoked

event ProverRevoked(address prover, uint64 version)

Issued when an existing prover is banished from the Reliquary

revoked provers may not issue new Relics or Artifacts. The meaning of any previously introduced Relics or Artifacts is implementation dependent.

Parameters

NameTypeDescription
proveraddressthe address of the prover contract
versionuint64the identifier that can never be used again

ProverInfo

struct ProverInfo {
uint64 version;
struct IReliquary.FeeInfo feeInfo;
bool revoked;
}

FeeFlags

enum FeeFlags {
FeeNone,
FeeNative,
FeeCredits,
FeeExternalDelegate,
FeeExternalToken
}

FeeInfo

struct FeeInfo {
uint8 flags;
uint16 feeCredits;
uint8 feeWeiMantissa;
uint8 feeWeiExponent;
uint32 feeExternalId;
}

ADD_PROVER_ROLE

function ADD_PROVER_ROLE() external view returns (bytes32)

CREDITS_ROLE

function CREDITS_ROLE() external view returns (bytes32)

DELAY

function DELAY() external view returns (uint64)

GOVERNANCE_ROLE

function GOVERNANCE_ROLE() external view returns (bytes32)

SUBSCRIPTION_ROLE

function SUBSCRIPTION_ROLE() external view returns (bytes32)

activateProver

function activateProver(address prover) external

activates a pending prover once the delay has passed. Callable by anyone.

Parameters

NameTypeDescription
proveraddressthe address of the pending prover

addCredits

function addCredits(address user, uint192 amount) external

Add credits to an account. Requires the CREDITS_ROLE.

Parameters

NameTypeDescription
useraddressThe account to which more credits should be granted
amountuint192The number of credits to be added

addProver

function addProver(address prover, uint64 version) external

Add/propose a new prover to prove facts. Requires the ADD_PROVER_ROLE.

Provers and proposed provers must have unique version IDs After the Reliquary is initialized, a review period of 64k blocks must conclude before a prover may be added. The request must then be re-submitted to take effect. Before initialization is complete, the review period is skipped. Emits PendingProverAdded when a prover is proposed for inclusion

Parameters

NameTypeDescription
proveraddressthe address of the prover in question
versionuint64the unique version string to associate with this prover

addSubscriber

function addSubscriber(address user, uint64 ts) external

Add/update a subscription. Requires the SUBSCRIPTION_ROLE.

Parameters

NameTypeDescription
useraddressThe subscriber account to modify
tsuint64The new block timestamp at which the subscription expires

assertValidBlockHash

function assertValidBlockHash(address verifier, bytes32 hash, uint256 num, bytes proof) external payable

Asserts that a particular block had a particular hash

Reverts if the given block was not proven to have the given hash. A fee may be required based on the block in question

Parameters

NameTypeDescription
verifieraddressThe block history verifier to use for the query
hashbytes32The block hash in question
numuint256The block number to query
proofbytesAny witness information needed by the verifier

assertValidBlockHashFromProver

function assertValidBlockHashFromProver(address verifier, bytes32 hash, uint256 num, bytes proof) external view

Asserts that a particular block had a particular hash. Callable only from provers.

Reverts if the given block was not proven to have the given hash. This function is only for use by provers (reverts otherwise)

Parameters

NameTypeDescription
verifieraddressThe block history verifier to use for the query
hashbytes32The block hash in question
numuint256The block number to query
proofbytesAny witness information needed by the verifier

checkProveFactFee

function checkProveFactFee(address sender) external payable

Require that an appropriate fee is paid for proving a fact

The fee is derived from the prover which calls this function Reverts if the fee is not sufficient Only to be called by a prover

Parameters

NameTypeDescription
senderaddressThe account wanting to prove a fact

checkProver

function checkProver(struct IReliquary.ProverInfo prover) external pure

Helper function to query the status of a prover

reverts if the prover is invalid or revoked

Parameters

NameTypeDescription
proverstruct IReliquary.ProverInfothe ProverInfo associated with the prover in question

credits

function credits(address user) external view returns (uint192)

Check how many credits a given account possesses

Parameters

NameTypeDescription
useraddressThe account in question

Return Values

NameTypeDescription
0uint192The number of credits

debugValidBlockHash

function debugValidBlockHash(address verifier, bytes32 hash, uint256 num, bytes proof) external view returns (bool)

Verify if a particular block had a particular hash. Only callable by address(0), for debug

This function is for use by off-chain tools only (reverts otherwise)

Parameters

NameTypeDescription
verifieraddressThe block history verifier to use for the query
hashbytes32The block hash in question
numuint256The block number to query
proofbytesAny witness information needed by the verifier

Return Values

NameTypeDescription
0boolboolean indication of whether or not the given block was proven to have the given hash.

debugVerifyFact

function debugVerifyFact(address account, FactSignature factSig) external view returns (bool exists, uint64 version, bytes data)

Query for associated information for a fact. Only callable by address(0), for debug

This function is for use by off-chain tools only (reverts otherwise)

Parameters

NameTypeDescription
accountaddressThe address to which the fact belongs
factSigFactSignatureThe unique signature identifying the fact

Return Values

NameTypeDescription
existsboolwhether or not a fact with the given signature is associated with the queried account
versionuint64the prover version id that proved this fact
databytesany associated fact data

factFees

function factFees(uint8) external view returns (struct IReliquary.FeeInfo)

feeAccounts

function feeAccounts(address) external view returns (uint64 subscriberUntilTime, uint192 credits)

feeExternals

function feeExternals(uint256) external view returns (address)

getFact

function getFact(address account, FactSignature factSig) external view returns (bool exists, uint64 version, bytes data)

Query for associated information for a fact. Only callable from provers.

This function is only for use by provers (reverts otherwise)

Parameters

NameTypeDescription
accountaddressThe address to which the fact belongs
factSigFactSignatureThe unique signature identifying the fact

Return Values

NameTypeDescription
existsboolwhether or not a fact with the given signature is associated with the queried account
versionuint64the prover version id that proved this fact
databytesany associated fact data

getProveFactNativeFee

function getProveFactNativeFee(address prover) external view returns (uint256)

Determine the appropriate ETH fee to prove a fact

Reverts if the fee is not to be paid in ETH

Parameters

NameTypeDescription
proveraddressThe prover of the desired fact

Return Values

NameTypeDescription
0uint256the fee in wei

getProveFactTokenFee

function getProveFactTokenFee(address prover) external view returns (uint256)

Determine the appropriate token fee to prove a fact

Reverts if the fee is not to be paid in external tokens

Parameters

NameTypeDescription
proveraddressThe prover of the desired fact

Return Values

NameTypeDescription
0uint256the fee in wei

getVerifyFactNativeFee

function getVerifyFactNativeFee(FactSignature factSig) external view returns (uint256)

Determine the appropriate ETH fee to query a fact

Reverts if the fee is not to be paid in ETH

Parameters

NameTypeDescription
factSigFactSignatureThe signature of the desired fact

Return Values

NameTypeDescription
0uint256the fee in wei

getVerifyFactTokenFee

function getVerifyFactTokenFee(FactSignature factSig) external view returns (uint256)

Determine the appropriate token fee to query a fact

Reverts if the fee is not to be paid in external tokens

Parameters

NameTypeDescription
factSigFactSignatureThe signature of the desired fact

Return Values

NameTypeDescription
0uint256the fee in wei

initialized

function initialized() external view returns (bool)

isSubscriber

function isSubscriber(address user) external view returns (bool)

Check if an account has an active subscription

Parameters

NameTypeDescription
useraddressThe account in question

Return Values

NameTypeDescription
0boolTrue if the account is active, otherwise false

pendingProvers

function pendingProvers(address) external view returns (uint64 timestamp, uint64 version)

provers

function provers(address) external view returns (struct IReliquary.ProverInfo)

removeCredits

function removeCredits(address user, uint192 amount) external

Remove credits from an account. Requires the CREDITS_ROLE.

Parameters

NameTypeDescription
useraddressThe account from which credits should be removed
amountuint192The number of credits to be removed

removeSubscriber

function removeSubscriber(address user) external

Remove a subscription. Requires the SUBSCRIPTION_ROLE.

Parameters

NameTypeDescription
useraddressThe subscriber account to modify

resetFact

function resetFact(address account, FactSignature factSig) external

Deletes the fact from the Reliquary. Only callable from provers.

May only be called by non-revoked provers

Parameters

NameTypeDescription
accountaddressThe account to which this information is bound (may be the null account for information bound to no specific address)
factSigFactSignatureThe unique signature of the particular fact being deleted

revokeProver

function revokeProver(address prover) external

Stop accepting proofs from this prover. Requires the GOVERNANCE_ROLE.

Emits ProverRevoked Note: existing facts proved by the prover may still stand

Parameters

NameTypeDescription
proveraddressThe prover to banish from the reliquary

setCredits

function setCredits(address user, uint192 amount) external

setFact

function setFact(address account, FactSignature factSig, bytes data) external

Adds the given information to the Reliquary. Only callable from provers.

May only be called by non-revoked provers

Parameters

NameTypeDescription
accountaddressThe account to which this information is bound (may be the null account for information bound to no specific address)
factSigFactSignatureThe unique signature of the particular fact being proven
databytesAssociated data to store with this item

setFactFee

function setFactFee(uint8 cls, struct IReliquary.FeeInfo feeInfo, address feeExternal) external

Sets the FeeInfo for a particular fee class. Requires the GOVERNANCE_ROLE.

Parameters

NameTypeDescription
clsuint8The fee class
feeInfostruct IReliquary.FeeInfoThe FeeInfo to use for the class
feeExternaladdressAn external fee provider (token or delegate). If none is required, this should be set to 0.

setInitialized

function setInitialized() external

Initialize the Reliquary, enforcing the time lock for new provers. Requires the ADD_PROVER_ROLE.

setProverFee

function setProverFee(address prover, struct IReliquary.FeeInfo feeInfo, address feeExternal) external

Sets the FeeInfo for a particular prover. Requires the GOVERNANCE_ROLE.

Parameters

NameTypeDescription
proveraddressThe prover in question
feeInfostruct IReliquary.FeeInfoThe FeeInfo to use for the class
feeExternaladdressAn external fee provider (token or delegate). If none is required, this should be set to 0.

setValidBlockFee

function setValidBlockFee(struct IReliquary.FeeInfo feeInfo, address feeExternal) external

Sets the FeeInfo for block verification. Requires the GOVERNANCE_ROLE.

Parameters

NameTypeDescription
feeInfostruct IReliquary.FeeInfoThe FeeInfo to use for the class
feeExternaladdressAn external fee provider (token or delegate). If none is required, this should be set to 0.

validBlockHash

function validBlockHash(address verifier, bytes32 hash, uint256 num, bytes proof) external payable returns (bool)

Verify if a particular block had a particular hash

A fee may be required based on the block in question

Parameters

NameTypeDescription
verifieraddressThe block history verifier to use for the query
hashbytes32The block hash in question
numuint256The block number to query
proofbytesAny witness information needed by the verifier

Return Values

NameTypeDescription
0boolboolean indication of whether or not the given block was proven to have the given hash.

validBlockHashFromProver

function validBlockHashFromProver(address verifier, bytes32 hash, uint256 num, bytes proof) external view returns (bool)

Verify if a particular block had a particular hash. Only callable from provers.

This function is only for use by provers (reverts otherwise)

Parameters

NameTypeDescription
verifieraddressThe block history verifier to use for the query
hashbytes32The block hash in question
numuint256The block number to query
proofbytesAny witness information needed by the verifier

Return Values

NameTypeDescription
0boolboolean indication of whether or not the given block was proven to have the given hash.

verifyBlockFeeInfo

function verifyBlockFeeInfo() external view returns (struct IReliquary.FeeInfo)

FeeInfo struct for block hash queries

verifyFact

function verifyFact(address account, FactSignature factSig) external payable returns (bool exists, uint64 version, bytes data)

Query for associated information for a fact

A fee may be required based on the factSig

Parameters

NameTypeDescription
accountaddressThe address to which the fact belongs
factSigFactSignatureThe unique signature identifying the fact

Return Values

NameTypeDescription
existsboolwhether or not a fact with the given signature is associated with the queried account
versionuint64the prover version id that proved this fact
databytesany associated fact data

verifyFactNoFee

function verifyFactNoFee(address account, FactSignature factSig) external view returns (bool exists, uint64 version, bytes data)

Query for associated information for a fact which requires no query fee.

This function is for use by anyone This function reverts if the fact requires a fee to query

Parameters

NameTypeDescription
accountaddressThe address to which the fact belongs
factSigFactSignatureThe unique signature identifying the fact

Return Values

NameTypeDescription
existsboolwhether or not a fact with the given signature is associated with the queried account
versionuint64the prover version id that proved this fact
databytesany associated fact data

verifyFactVersion

function verifyFactVersion(address account, FactSignature factSig) external payable returns (bool exists, uint64 version)

Query for the prover version for a fact

A fee may be required based on the factSig

Parameters

NameTypeDescription
accountaddressThe address to which the fact belongs
factSigFactSignatureThe unique signature identifying the fact

Return Values

NameTypeDescription
existsboolwhether or not a fact with the given signature is associated with the queried account
versionuint64the prover version id that proved this fact

verifyFactVersionNoFee

function verifyFactVersionNoFee(address account, FactSignature factSig) external view returns (bool exists, uint64 version)

Query for the prover version for a fact which requires no query fee.

This function is for use by anyone This function reverts if the fact requires a fee to query

Parameters

NameTypeDescription
accountaddressThe address to which the fact belongs
factSigFactSignatureThe unique signature identifying the fact

Return Values

NameTypeDescription
existsboolwhether or not a fact with the given signature is associated with the queried account
versionuint64the prover version id that proved this fact

versions

function versions(uint64) external view returns (address)

Reverse mapping of version information to the unique prover able to issue statements with that version

withdrawFees

function withdrawFees(address token, address dest) external

Extract accumulated fees. Requires the GOVERNANCE_ROLE.

Parameters

NameTypeDescription
tokenaddressThe ERC20 token from which to extract fees. Or the 0 address for native ETH
destaddressThe address to which fees should be transferred

BirthCertificate

Helper functions for handling birth certificate facts

File: lib/BirthCertificate.sol

parse

function parse(bytes data) internal pure returns (uint48 blockNum, uint64 time)

parse a birth certificate fact

Parameters

NameTypeDescription
databytesthe stored fact data

Return Values

NameTypeDescription
blockNumuint48the blockNum from the birth certificate
timeuint64the timestamp from the birth certificate

BytesCalldata

BytesCalldataOps

Common operations for bytes calldata, implemented for both the builtin type and our BytesCalldata type. These operations are heavily optimized and omit safety checks, so this library should only be used when memory safety is not a security issue.

File: lib/BytesCalldata.sol

length

function length(BytesCalldata bc) internal pure returns (uint256 result)

offset

function offset(BytesCalldata bc) internal pure returns (uint256 result)

convert

function convert(BytesCalldata bc) internal pure returns (bytes value)

convert

function convert(bytes inp) internal pure returns (BytesCalldata bc)

slice

function slice(BytesCalldata bc, uint256 start, uint256 len) internal pure returns (BytesCalldata result)

slice

function slice(bytes value, uint256 start, uint256 len) internal pure returns (bytes result)

prefix

function prefix(BytesCalldata bc, uint256 len) internal pure returns (BytesCalldata result)

prefix

function prefix(bytes value, uint256 len) internal pure returns (bytes result)

suffix

function suffix(BytesCalldata bc, uint256 start) internal pure returns (BytesCalldata result)

suffix

function suffix(bytes value, uint256 start) internal pure returns (bytes result)

split

function split(BytesCalldata bc, uint256 start) internal pure returns (BytesCalldata, BytesCalldata)

split

function split(bytes value, uint256 start) internal pure returns (bytes, bytes)

CoreTypes

Data types and parsing functions for core types, including block headers and account data.

File: lib/CoreTypes.sol

BlockHeaderData

struct BlockHeaderData {
bytes32 ParentHash;
address Coinbase;
bytes32 Root;
bytes32 TxHash;
bytes32 ReceiptHash;
uint256 Number;
uint256 GasLimit;
uint256 GasUsed;
uint256 Time;
bytes32 MixHash;
uint256 BaseFee;
bytes32 WithdrawalsHash;
}

AccountData

struct AccountData {
uint256 Nonce;
uint256 Balance;
bytes32 StorageRoot;
bytes32 CodeHash;
}

LogData

struct LogData {
address Address;
bytes32[] Topics;
bytes Data;
}

WithdrawalData

struct WithdrawalData {
uint256 Index;
uint256 ValidatorIndex;
address Address;
uint256 AmountInGwei;
}

parseHash

function parseHash(bytes buf) internal pure returns (bytes32 result, uint256 offset)

parseAddress

function parseAddress(bytes buf) internal pure returns (address result, uint256 offset)

parseBlockHeader

function parseBlockHeader(bytes header) internal pure returns (struct CoreTypes.BlockHeaderData data)

getBlockHeaderHashAndSize

function getBlockHeaderHashAndSize(bytes header) internal pure returns (bytes32 blockHash, uint256 headerSize)

parseAccount

function parseAccount(bytes account) internal pure returns (struct CoreTypes.AccountData data)

parseLog

function parseLog(bytes log) internal pure returns (struct CoreTypes.LogData data)

extractLog

function extractLog(bytes receiptValue, uint256 logIdx) internal pure returns (struct CoreTypes.LogData)

parseWithdrawal

function parseWithdrawal(bytes withdrawal) internal pure returns (struct CoreTypes.WithdrawalData data)

FactSigs

Helper functions for computing fact signatures

File: lib/FactSigs.sol

birthCertificateFactSigData

function birthCertificateFactSigData() internal pure returns (bytes)

Produce the fact signature data for birth certificates

birthCertificateFactSig

function birthCertificateFactSig() internal pure returns (FactSignature)

Produce the fact signature for a birth certificate fact

accountStorageFactSigData

function accountStorageFactSigData(uint256 blockNum, bytes32 storageRoot) internal pure returns (bytes)

Produce the fact signature data for an account's storage root

Parameters

NameTypeDescription
blockNumuint256the block number to look at
storageRootbytes32the storageRoot for the account

accountStorageFactSig

function accountStorageFactSig(uint256 blockNum, bytes32 storageRoot) internal pure returns (FactSignature)

Produce a fact signature for an account storage root

Parameters

NameTypeDescription
blockNumuint256the block number to look at
storageRootbytes32the storageRoot for the account

accountCodeHashFactSigData

function accountCodeHashFactSigData(uint256 blockNum, bytes32 codeHash) internal pure returns (bytes)

Produce the fact signature data for an account's code hash

Parameters

NameTypeDescription
blockNumuint256the block number to look at
codeHashbytes32the codeHash for the account

accountCodeHashFactSig

function accountCodeHashFactSig(uint256 blockNum, bytes32 codeHash) internal pure returns (FactSignature)

Produce a fact signature for an account code hash

Parameters

NameTypeDescription
blockNumuint256the block number to look at
codeHashbytes32the codeHash for the account

accountNonceFactSigData

function accountNonceFactSigData(uint256 blockNum) internal pure returns (bytes)

Produce the fact signature data for an account's nonce at a block

Parameters

NameTypeDescription
blockNumuint256the block number to look at

accountNonceFactSig

function accountNonceFactSig(uint256 blockNum) internal pure returns (FactSignature)

Produce a fact signature for an account nonce at a block

Parameters

NameTypeDescription
blockNumuint256the block number to look at

accountBalanceFactSigData

function accountBalanceFactSigData(uint256 blockNum) internal pure returns (bytes)

Produce the fact signature data for an account's balance at a block

Parameters

NameTypeDescription
blockNumuint256the block number to look at

accountBalanceFactSig

function accountBalanceFactSig(uint256 blockNum) internal pure returns (FactSignature)

Produce a fact signature for an account balance a block

Parameters

NameTypeDescription
blockNumuint256the block number to look at

accountFactSigData

function accountFactSigData(uint256 blockNum) internal pure returns (bytes)

Produce the fact signature data for an account's raw header

Parameters

NameTypeDescription
blockNumuint256the block number to look at

accountFactSig

function accountFactSig(uint256 blockNum) internal pure returns (FactSignature)

Produce a fact signature for an account raw header

Parameters

NameTypeDescription
blockNumuint256the block number to look at

storageSlotFactSigData

function storageSlotFactSigData(bytes32 slot, uint256 blockNum) internal pure returns (bytes)

Produce the fact signature data for a storage slot

Parameters

NameTypeDescription
slotbytes32the account's slot
blockNumuint256the block number to look at

storageSlotFactSig

function storageSlotFactSig(bytes32 slot, uint256 blockNum) internal pure returns (FactSignature)

Produce a fact signature for a storage slot

Parameters

NameTypeDescription
slotbytes32the account's slot
blockNumuint256the block number to look at

logFactSigData

function logFactSigData(uint256 blockNum, uint256 txIdx, uint256 logIdx) internal pure returns (bytes)

Produce the fact signature data for a log

Parameters

NameTypeDescription
blockNumuint256the block number to look at
txIdxuint256the transaction index in the block
logIdxuint256the log index in the transaction

logFactSig

function logFactSig(uint256 blockNum, uint256 txIdx, uint256 logIdx) internal pure returns (FactSignature)

Produce a fact signature for a log

Parameters

NameTypeDescription
blockNumuint256the block number to look at
txIdxuint256the transaction index in the block
logIdxuint256the log index in the transaction

blockHeaderSigData

function blockHeaderSigData(uint256 blockNum) internal pure returns (bytes)

Produce the fact signature data for a block header

Parameters

NameTypeDescription
blockNumuint256the block number

blockHeaderSig

function blockHeaderSig(uint256 blockNum) internal pure returns (FactSignature)

Produce the fact signature data for a block header

Parameters

NameTypeDescription
blockNumuint256the block number

withdrawalSigData

function withdrawalSigData(uint256 blockNum, uint256 index) internal pure returns (bytes)

Produce the fact signature data for a withdrawal

Parameters

NameTypeDescription
blockNumuint256the block number
indexuint256the withdrawal index

withdrawalFactSig

function withdrawalFactSig(uint256 blockNum, uint256 index) internal pure returns (FactSignature)

Produce the fact signature for a withdrawal

Parameters

NameTypeDescription
blockNumuint256the block number
indexuint256the withdrawal index

eventFactSigData

function eventFactSigData(uint64 eventId) internal pure returns (bytes)

Produce the fact signature data for an event fact

Parameters

NameTypeDescription
eventIduint64The event in question

eventFactSig

function eventFactSig(uint64 eventId) internal pure returns (FactSignature)

Produce a fact signature for a given event

Parameters

NameTypeDescription
eventIduint64The event in question

transactionFactSigData

function transactionFactSigData(bytes32 transaction) internal pure returns (bytes)

Produce the fact signature data for a transaction fact

Parameters

NameTypeDescription
transactionbytes32the transaction hash to be proven

transactionFactSig

function transactionFactSig(bytes32 transaction) internal pure returns (FactSignature)

Produce a fact signature for a transaction

Parameters

NameTypeDescription
transactionbytes32the transaction hash to be proven

FactSignature

Fact

struct Fact {
address account;
FactSignature sig;
bytes data;
}

Facts

Helper functions for fact classes (part of fact signature that determines fee).

File: lib/Facts.sol

NO_FEE

uint8 NO_FEE

toFactSignature

function toFactSignature(uint8 cls, bytes data) internal pure returns (FactSignature)

construct a fact signature from a fact class and some unique data

Parameters

NameTypeDescription
clsuint8the fact class (determines the fee)
databytesthe unique data for the signature

toFactClass

function toFactClass(FactSignature factSig) internal pure returns (uint8)

extracts the fact class from a fact signature

Parameters

NameTypeDescription
factSigFactSignaturethe input fact signature

RLP

Gas optimized RLP parsing code. Note that some parsing logic is duplicated because helper functions are oddly expensive.

File: lib/RLP.sol

parseUint

function parseUint(bytes buf) internal pure returns (uint256 result, uint256 size)

nextSize

function nextSize(bytes buf) internal pure returns (uint256 size)

skip

function skip(bytes buf) internal pure returns (bytes)

parseList

function parseList(bytes buf) internal pure returns (uint256 listSize, uint256 offset)

splitBytes

function splitBytes(bytes buf) internal pure returns (bytes result, bytes rest)

encodeUint

function encodeUint(uint256 value) internal pure returns (bytes)

Storage

Helper functions for handling storage slot facts and computing storage slots

File: lib/Storage.sol

mapElemSlot

function mapElemSlot(bytes32 base, bytes32 key) internal pure returns (bytes32)

compute the slot for an element of a mapping

Parameters

NameTypeDescription
basebytes32the slot of the struct base
keybytes32the mapping key, padded to 32 bytes

staticArrayElemSlot

function staticArrayElemSlot(bytes32 base, uint256 idx, uint256 slotsPerElem) internal pure returns (bytes32)

compute the slot for an element of a static array

Parameters

NameTypeDescription
basebytes32the slot of the struct base
idxuint256the index of the element
slotsPerElemuint256the number of slots per element

dynamicArrayElemSlot

function dynamicArrayElemSlot(bytes32 base, uint256 idx, uint256 slotsPerElem) internal pure returns (bytes32)

compute the slot for an element of a dynamic array

Parameters

NameTypeDescription
basebytes32the slot of the struct base
idxuint256the index of the element
slotsPerElemuint256the number of slots per element

structFieldSlot

function structFieldSlot(bytes32 base, uint256 offset) internal pure returns (bytes32)

compute the slot for a struct field given the base slot and offset

Parameters

NameTypeDescription
basebytes32the slot of the struct base
offsetuint256the slot offset in the struct

_parseUint256

function _parseUint256(bytes data) internal pure returns (uint256)

parseUint256

function parseUint256(bytes data) internal pure returns (uint256)

parse a uint256 from storage slot bytes

Parameters

NameTypeDescription
databytesthe storage slot bytes

Return Values

NameTypeDescription
0uint256address the parsed address

parseUint64

function parseUint64(bytes data) internal pure returns (uint64)

parse a uint64 from storage slot bytes

Parameters

NameTypeDescription
databytesthe storage slot bytes

parseAddress

function parseAddress(bytes data) internal pure returns (address)

parse an address from storage slot bytes

Parameters

NameTypeDescription
databytesthe storage slot bytes

IBatchProver

IBatchProver is a standard interface implemented by some Relic provers. Supports proving multiple facts ephemerally or proving and storing them in the Reliquary.

File: interfaces/IBatchProver.sol

proveBatch

function proveBatch(bytes proof, bool store) external payable returns (struct Fact[] facts)

prove multiple facts ephemerally

Parameters

NameTypeDescription
proofbytesthe encoded proof, depends on the prover implementation
storeboolwhether to store the facts in the reliquary

Return Values

NameTypeDescription
factsstruct Factthe proven facts' information

IProver

IProver is a standard interface implemented by some Relic provers. Supports proving a fact ephemerally or proving and storing it in the Reliquary.

File: interfaces/IProver.sol

prove

function prove(bytes proof, bool store) external payable returns (struct Fact fact)

prove a fact and optionally store it in the Reliquary

Parameters

NameTypeDescription
proofbytesthe encoded proof, depends on the prover implementation
storeboolwhether to store the facts in the reliquary

Return Values

NameTypeDescription
factstruct Factthe proven fact information

IAttendanceProver

IAttendanceProver verifies statements signed by trusted sources to assign attendance Artifacts to accounts

File: interfaces/IAttendanceProver.sol

NewEvent

event NewEvent(uint64 eventId, uint48 deadline, FactSignature factSig)

Emitted when a new event which may be attended is created

Parameters

NameTypeDescription
eventIduint64The unique id of this event
deadlineuint48The timestamp after which no further attendance requests will be processed
factSigFactSignatureThe fact signature of this particular event

addEvent

function addEvent(uint64 eventId, address signer, uint48 deadline, uint32 capacity) external

Add a new event which may be attended

Emits NewEvent

Parameters

NameTypeDescription
eventIduint64The unique eventId for the new event
signeraddressThe address for the signer which attests the claim code is valid
deadlineuint48The timestamp after which no further attendance requests will be processed
capacityuint32The initial maximum number of attendees which can claim codes

claim

function claim(address account, uint64 eventId, uint64 number, bytes signatureInner, bytes signatureOuter) external payable

Prove attendance for an event and claim the associated conveyances

Issues a fact in the Reliquary with the fact signature for this event Issues a soul-bound NFT Artifact for attending the event

Parameters

NameTypeDescription
accountaddressThe account making the claim of attendance
eventIduint64The event which was attended
numberuint64The unique id which may be redeemed only once from the event
signatureInnerbytesThe signature attesting that the number and eventId are valid
signatureOuterbytesThe signature attesting that the account is the claimer of the presented information

events

function events(uint64) external view returns (address signer, uint32 capacity, uint48 deadline)

increaseCapacity

function increaseCapacity(uint64 eventId, uint32 newCapacity) external

Increase the capacity of an existing event. Only callable by the contract owner.

Emits NewEvent

Parameters

NameTypeDescription
eventIduint64The unique eventId for the new event is valid
newCapacityuint32the new maximum number of attendees which can claim codes

outerSigner

function outerSigner() external view returns (address)

setOuterSigner

function setOuterSigner(address _outerSigner) external

Sets the signer for the attestation that a request was made by a particular account. Only callable by the contract owner.

Parameters

NameTypeDescription
_outerSigneraddressThe address corresponding to the signer

IBirthCertificateProver

IBirthCertificateProver proves that an account existed in a given block and stores the oldest known account proof in the fact database

File: interfaces/IBirthCertificateProver.sol

BIRTH_CERTIFICATE_SIG

function BIRTH_CERTIFICATE_SIG() external view returns (FactSignature)

blockHistory

function blockHistory() external view returns (address)

proveBirthCertificate

function proveBirthCertificate(address account, bytes accountProof, bytes header, bytes blockProof) external payable

Proves that an account existed in the given block. Stores the fact in the registry if the given block is the oldest block this account is known to exist in. Mints the account an SBT if this is the first proof.

Parameters

NameTypeDescription
accountaddressthe account to prove exists
accountProofbytesthe Merkle-Patricia trie proof for the account
headerbytesthe block header, RLP encoded
blockProofbytesproof that the block header is valid

IStorageSlotProver

IStorageSlotProver proves that a storage slot had a particular value at a particular block.

File: interfaces/IStorageSlotProver.sol

blockHistory

function blockHistory() external view returns (address)

proveAndStoreStorageSlot

function proveAndStoreStorageSlot(address account, bytes accountProof, bytes32 slot, bytes slotProof, bytes header, bytes blockProof) external payable returns (uint256 blockNum, bytes value)

Proves that a storage slot had a particular value at a particular block, and stores this fact in the reliquary.

Parameters

NameTypeDescription
accountaddressthe account to prove exists
accountProofbytesthe Merkle-Patricia trie proof for the account
slotbytes32the storage slot index
slotProofbytesthe Merkle-Patricia trie proof for the slot
headerbytesthe block header, RLP encoded
blockProofbytesproof that the block header is valid

Return Values

NameTypeDescription
blockNumuint256the block number from the header
valuebytesthe bytes value of the data in the slot

proveStorageSlot

function proveStorageSlot(address account, bytes accountProof, bytes32 slot, bytes slotProof, bytes header, bytes blockProof) external payable returns (uint256, bytes)

Proves that a storage slot had a particular value at a particular block. Returns the block number and bytes value of the slot.

Parameters

NameTypeDescription
accountaddressthe account to prove exists
accountProofbytesthe Merkle-Patricia trie proof for the account
slotbytes32the storage slot index
slotProofbytesthe Merkle-Patricia trie proof for the slot
headerbytesthe block header, RLP encoded
blockProofbytesproof that the block header is valid
Table of Contents