This document provides an overview and integration guide for our smart contract, available as an npm package. You can install it with:
npm i @selfxyz/contracts
Package Structure and Overview
The package structure and a brief explanation for each part are as follows:
.
├── abstract
│ └── SelfVerificationRoot.sol # Base impl in self verification
├── constants
│ ├── AttestationId.sol # A unique identifier assigned to the identity documents
│ └── CircuitConstants.sol # Indices for public signals in our circuits
├── interfaces # Interfaces for each contract
│ ├── IDscCircuitVerifier.sol
│ ├── IIdentityRegistryV1.sol
│ ├── IIdentityVerificationHubV1.sol
│ ├── IPassportAirdropRoot.sol
│ ├── IRegisterCircuitVerifier.sol
│ ├── ISelfVerificationRoot.sol
│ └── IVcAndDiscloseCircuitVerifier.sol
└── libraries
├── CircuitAttributeHandler.sol # Library to extract each attribute from public signals
└── Formatter.sol # Utility functions to manage public signals to meaningful format
Basic Integration Strategy
To leverage the apps and infrastructure provided by Self, extend the SelfVerificationRoot contract and use the verifySelfProof function. Since SelfVerificationRoot already contains a simple implementation, you usually won’t need to add extra code. For example:
import {SelfVerificationRoot} from "../abstract/SelfVerificationRoot.sol";
contract Example is SelfVerificationRoot {
constructor(
address _identityVerificationHub,
uint256 _scope,
uint256 _attestationId,
bool _olderThanEnabled,
uint256 _olderThan,
bool _forbiddenCountriesEnabled,
uint256[4] memory _forbiddenCountriesListPacked,
bool[3] memory _ofacEnabled
)
SelfVerificationRoot(
_identityVerificationHub, // Address of our Verification Hub, e.g., "0x77117D60eaB7C044e785D68edB6C7E0e134970Ea"
_scope, // An application-specific identifier for the integrated contract
_attestationId, // The id specifying the type of document to verify (e.g., 1 for passports)
_olderThanEnabled, // Flag to enable age verification
_olderThan, // The minimum age required for verification
_forbiddenCountriesEnabled, // Flag to enable forbidden countries verification
_forbiddenCountriesListPacked, // Packed data representing the list of forbidden countries
_ofacEnabled // Flag to enable OFAC check
)
{}
}
Application Integration:
In your third-party application (which integrates our SDK), specify the target contract address for verification.
User Interaction:
The user scans their passport on their device. The passport data, along with the contract address specified by your application, is sent to our TEE (Trusted Execution Environment) server.
Proof Generation:
Our TEE server generates a proof based on the passport information and automatically calls the specified contract address.
Fixed Interface:
The called contract uses a fixed interface—the verifySelfProof function in the abstract contract SelfVerificationRoot—ensuring consistency across integrations.
Parameters: olderThan, forbiddenCountries, and ofacEnabled
These parameters serve to both verify the correctness of the Groth16 proof and validate the public signals contained in the proof. The following points summarize their roles:
Verification:
They ensure the proof is valid and that the public signals are correct. This validation is performed by our IdentityVerificationHub.
Configuration:
Set the minimum age (olderThan), the list of forbidden countries, and the type of OFAC check on each contract that integrates our system.
Proof Verification in IdentityVerificationHub
The following Solidity function shows how the IdentityVerificationHub verifies the proof:
function _verifyVcAndDiscloseProof(
VcAndDiscloseHubProof memory proof
)
internal
view
returns (uint256 identityCommitmentRoot)
{
// verify identity commitment root
if (!IIdentityRegistryV1(_registry).checkIdentityCommitmentRoot(proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_MERKLE_ROOT_INDEX])) {
revert INVALID_COMMITMENT_ROOT();
}
// verify current date
uint[6] memory dateNum;
for (uint256 i = 0; i < 6; i++) {
dateNum[i] = proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_CURRENT_DATE_INDEX + i];
}
uint currentTimestamp = Formatter.proofDateToUnixTimestamp(dateNum);
if(
currentTimestamp < _getStartOfDayTimestamp() - 1 days + 1 ||
currentTimestamp > _getStartOfDayTimestamp() + 1 days - 1
) {
revert CURRENT_DATE_NOT_IN_VALID_RANGE();
}
// verify attributes
uint256[3] memory revealedDataPacked;
for (uint256 i = 0; i < 3; i++) {
revealedDataPacked[i] = proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_REVEALED_DATA_PACKED_INDEX + i];
}
if (proof.olderThanEnabled) {
if (!CircuitAttributeHandler.compareOlderThan(Formatter.fieldElementsToBytes(revealedDataPacked), proof.olderThan)) {
revert INVALID_OLDER_THAN();
}
}
if (proof.ofacEnabled[0] || proof.ofacEnabled[1] || proof.ofacEnabled[2]) {
if (!CircuitAttributeHandler.compareOfac(
Formatter.fieldElementsToBytes(revealedDataPacked),
proof.ofacEnabled[0],
proof.ofacEnabled[1],
proof.ofacEnabled[2]
)) {
revert INVALID_OFAC();
}
if (!IIdentityRegistryV1(_registry).checkOfacRoots(
proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_PASSPORT_NO_SMT_ROOT_INDEX],
proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_NAME_DOB_SMT_ROOT_INDEX],
proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_NAME_YOB_SMT_ROOT_INDEX]
)) {
revert INVALID_OFAC_ROOT();
}
}
if (proof.forbiddenCountriesEnabled) {
for (uint256 i = 0; i < 4; i++) {
if (
proof.forbiddenCountriesListPacked[i] != proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_FORBIDDEN_COUNTRIES_LIST_PACKED_INDEX + i]
) {
revert INVALID_FORBIDDEN_COUNTRIES();
}
}
}
// verify the proof using the VC and Disclose circuit verifier
if (!IVcAndDiscloseCircuitVerifier(_vcAndDiscloseCircuitVerifier).verifyProof(proof.vcAndDiscloseProof.a, proof.vcAndDiscloseProof.b, proof.vcAndDiscloseProof.c, proof.vcAndDiscloseProof.pubSignals)) {
revert INVALID_VC_AND_DISCLOSE_PROOF();
}
return proof.vcAndDiscloseProof.pubSignals[CircuitConstants.VC_AND_DISCLOSE_MERKLE_ROOT_INDEX];
}
Key Points in Proof Verification
Merkle Tree Usage:
The proof must be generated using the Merkle tree maintained in our registry.
Timestamp Verification:
The proof must have been generated recently, within a valid time window.
Older Than Check:
If enabled, the proof must contain a valid age verification:
For example, if the contract is set to require an age of 18, then a proof generated for a user who is 20 will pass. Conversely, if the contract requires a minimum of 20 and the user’s proof indicates 18, the verification will fail.
Forbidden Countries Check:
If enabled, you can specify forbidden nationalities.
The forbidden countries are represented as a packed list of three-letter country codes.
For gas efficiency, the check is performed on the packed data without unpacking.
Ensure that the order of the forbidden countries specified in your integrated application matches the forbiddenCountriesListPacked value in the contract.
OFAC Check:
Self supports OFAC checks against the U.S. Treasury’s sanctions list.
There are multiple OFAC verification methods:
ofacEnabled[0]: OFAC check using passport number.
ofacEnabled[1]: OFAC check using name and date of birth.
ofacEnabled[2]: OFAC check using name and year of birth.
Configure your contract to enable the same OFAC checks as those enabled in your application.
Enabled Flags:
The flags (olderThanEnabled, forbiddenCountriesEnabled, and ofacEnabled) allow you to save gas by skipping unnecessary verifications.
By following this guide, you should be able to integrate our smart contract into your application while maintaining flexibility over age restrictions, forbidden country checks, and OFAC verifications.
Feel free to adjust or extend the code and configuration according to your application’s needs.
