Circuits Catalog

Admin Circuits (`packages/contract/src/modules/Admin.compact`)

Circuit Signature	Description
`Admin_addIssuer(protocolName, contractAddress) → issuerPk: Bytes<32>`	Registers a new issuer and returns their derived public key. Requires super admin or admin authorization.
`Admin_removeIssuer(issuerPk)`	Removes a registered issuer.
`Admin_addAdmin(adminPk)`	Grants admin privileges to a new key. Only callable by super admin.
`Admin_removeAdmin(adminPk)`	Revokes admin privileges.
`Admin_updatedProtocolConfig(updatedConfig: ProtocolConfig)`	Updates tier thresholds and NFT validity.
`Admin_updatedScoreConfig(updatedScoreConfig: ScoreConfig)`	Updates score formula weights and bounds.
`Admin_updateTokenUris(tokenImageUris, scoreConfig)`	Updates IPFS URIs for tier token images.

NFT Circuits (`packages/contract/src/modules/PoTNFT.compact`)

Circuit Signature	Description
`Scoring_createScoreEntry(userPk: Bytes<32>)`	Initializes an empty credit score and accumulator in private state; commits both on-chain. One entry per Veil ID.
`Scoring_submitRepaymentEvent(userPk, issuerPk, paidOnTimeFlag: 0\|1, amountWeight, eventEpoch, eventId)`	Records a loan repayment. Updates `onTimeCount`, `lateCount`, `weightedRepaymentVolume`.
`Scoring_submitLiquidationEvent(userPk, issuerPk, severity: 1–3, eventEpoch, eventId)`	Records a liquidation. Penalty scaled by `severity × issuerTrustWeight`.
`Scoring_submitProtocolUsageEvent(userPk, issuerPk, protocolId, eventEpoch)`	Records a unique protocol interaction. Each `(user, protocol)` pair counted once.
`Scoring_submitDebtStateEvent(userPk, issuerPk, activeDebtFlag: 0\|1, riskBand: 0–3, eventEpoch, eventId)`	Records debt state snapshot. Currently scaffolded in the CLI but contract logic is complete.

Utility Circuits (`packages/contract/src/modules/Utils.compact`)

Circuit Signature	Description
`NFT_mintPoTNFT() → []`	Recomputes score, determines tier, mints shielded PoT token, registers metadata.
`NFT_renewPoTNFT(token: ShieldedCoinInfo)`	Burns old PoT token, recomputes score, mints fresh token with extended expiry.
`NFT_verifyPoTNFT(issuerPk, userPk, challenge, challengeExpiresAt, ownershipSecret) → Boolean`	Verifies NFT validity. Returns `true` = valid, `false` = expired/revoked.
`revokePoTNFT(userPk, adminPk)`	Admin-only forced revocation.

Utility Circuits (`packages/contract/src/modules/Utils.compact`)

Circuit Signature	Description
`Utils_initializeContractConfigurations(tokenImageUris, tokenName, protocolConfig, scoreConfig, tokenMarkers)`	One-time initialization of all protocol parameters.
`Utils_generateUserPk(sk: Bytes<32>) → Bytes<32>`	Derives a Veil ID from a secret key. Domain: `"veil:user"`.

Internal utility circuits (not directly callable as entry points):

generateIssuerPk — derives issuer key from secret: domain "veil:issuer"
generateAdminPk — derives admin key: domain "veil:superadmin"
assertAuthorization — checks caller’s derived key against superAdmin ledger state
recomputeAndPersistScore — full score recomputation pipeline with commitment updates
computeCurrentEpoch — lazy epoch advancement based on block timestamp
mintAndSendToken — shielded token issuance with nonce evolution

Last updated on April 25, 2026

API Integration Guide Monorepo Structure