Service layer
Pages never talk to contracts, RPC endpoints or server routes directly. They call services: small classes in src/services/ that each own one concern (credentials, status, documents, enrolment and so on). All services are built in one place, the composition root createServices(config) in src/services/index.ts, and handed to React through ServicesProvider. This keeps the wiring in one file, lets tests replace any dependency with a fake, and means a page cannot accidentally read through the wrong network or the wrong contract set.
Layers
| Layer | Folder | Job |
|---|---|---|
| Wallet | src/services/wallet/ | Talks to the injected EIP-1193 wallet: accounts, signatures, transactions, chain switching. See Wallet and network. |
| Gateways | src/services/contracts/, src/services/credentials/ | Turn addresses and ABIs into ethers Contract objects. A gateway offers a reader (public RPC, no wallet) and a writer (wallet signer, after a chain check). |
| Indexes | src/services/indexing/ | Rebuild lists from contract events with bounded log scans and caches. See Reading the chain. |
| Domain services | src/services/domain/ | The operations pages use: issue, check, revoke, enrol, share, disclose, export, prove access. |
| Routers and fan-outs | src/services/domain/ | Send a call to the contract set that holds a credential, or run a read in every set. See Contract-set routing. |
| React glue | src/services/react/ | ServicesProvider, useServices, useWalletSession, usePlatformPaused. |
| Server clients | src/services/upload.ts, src/services/document-api.ts | Browser side of sign-in, upload, document lookup and removal. See Upload and documents. |
The composition root
createServices receives a ServicesConfig:
| Field | Type | Meaning |
|---|---|---|
getEthereum | () => WalletEthereum or null | Returns the injected wallet. The browser passes window.ethereum; tests pass a fake or null. |
addressBook | AddressBook | academicRecords (v0.2 address), chainId (from NEXT_PUBLIC_NETWORK_ID, null if not a number), rpcUrls (public endpoints), startBlock (from NEXT_PUBLIC_START_BLOCK). Built by loadAddressBook() in src/services/contracts/address-book.ts. |
contractFactory | optional | Replaces new Contract(...) for the v0.2 gateway in tests. |
documentGateways | optional string[] | IPFS gateways for reading documents, best first. The browser passes gatewayList(NEXT_PUBLIC_PINATA_GATEWAY_URL): the configured gateway first, then https://ipfs.io and https://dweb.link. |
createBrowserServices() in src/services/react/browser-services.ts fills these from the browser and the NEXT_PUBLIC_* variables.
Inside, the root builds, in order:
- One
WalletService. - A
chainGuardthat throwsChainConfigErrorwhen no chain id is configured and otherwise callsassertCorrectChain(wallet.network(), chainId). Every writer runs it before sending a transaction. - Three gateways, all with
createDefaultReadRunneras their read runner (a failover RPC provider with an 8 second per-request timeout):createContractGatewayfor the v0.2AcademicRecordscontract.createCredentialGatewayfor the v0.3 registries. Addresses always come from the bundled deployment manifest (ADR-0040), never from an environment variable.createAccessGatewayfor the zero-knowledge access gate, fromsrc/contracts/zk/deployment.<chainId>.json.
- The per-set services of the active contract set, then the routers and fan-outs that reach the other sets.
- The v0.2 services, the chain-wide v0.3 services, the document service and the access services.
Per-set services
A credential lives in exactly one contract set, and every check of it must use that set's registries. createSetServices(gateway, wallet) builds one bundle of services on a gateway scoped to a single set. rememberPerGateway caches the bundle in a WeakMap keyed by the scoped gateway, so asking twice for the same set returns the same objects and their caches.
Field of SetServices | Class | Built from |
|---|---|---|
credentials | CredentialService | gateway, wallet |
status | StatusService | gateway |
recordTypes | RecordTypeService | gateway, index |
disclosure | DisclosureService | gateway, credentials, wallet as identity |
vc | VcService | gateway, credentials, and status list support from createVcLists |
presentation | PresentationService | gateway, credentials, disclosure |
issued | IssuedCredentialsService | index, status, recordTypes |
inbox | InboxService | gateway, index, status, recordTypes |
createVcLists returns status list support only when both NEXT_PUBLIC_STATUS_LIST_BASE_URL and NEXT_PUBLIC_STATUS_LIST_PUBLISHER are set. It builds a StatusListChecker that recomputes a credential's list position from the issuer's issuance order, pins the publisher address, and counts an issuance as stable only after 64 confirmations (STATUS_LIST_CONFIRMATIONS). Without both variables, exported VCs carry the chain status alone. See Status lists.
The Services object
These are the fields pages read through useServices().
| Field | Class (file in src/services/domain/ unless noted) | Depends on | What pages use it for | Version |
|---|---|---|---|---|
wallet | WalletService (src/services/wallet/wallet-service.ts) | injected wallet | Connect, address, sign, switch chain, change events | both |
roles | RoleService (role-service.ts) | v0.2 gateway | hasRole, isRegisteredUniversity | v0.2 |
universities | UniversityService (university-service.ts) | v0.2 gateway | Add, remove, rename universities | v0.2 |
students | StudentService (student-service.ts) | v0.2 gateway | Register students, migrate wallets | v0.2 |
records | RecordService (record-service.ts) | v0.2 gateway | Add and read records, verify a record | v0.2 |
sharing | SharingService (sharing-service.ts) | v0.2 gateway, LogShareIndex | Share and unshare, "shared with me" lists | v0.2 |
governance | GovernanceService (governance-service.ts) | v0.2 gateway | Admins, custom types, pause | v0.2 |
credentials | CredentialService (credential-service.ts) | active set | Issue, read, check a document or package, signatures, issuer lineage | v0.3 |
locator | CredentialLocator (credential-locator.ts) | credential gateway, per-set services | Find the set that holds a credential id | v0.3 |
anchors | createRoutedCredentials (routed-credentials.ts) | locator | getCredential from whichever set holds it | v0.3 |
documents | DocumentService (document-service.ts) | credential gateway, wallet, anchors, document API, IPFS gateways | Encrypt and upload, open as issuer or holder, grants, capability links, key replacement, removal of old copies | v0.3 |
status | StatusService (status-service.ts) | active set | Suspend, reinstate, revoke, supersede | v0.3 |
enrolment | EnrolmentService (enrolment-service.ts) | credential gateway, wallet | Invitations, redeeming, bindings | v0.3 |
inbox | AllSetsInbox (all-sets-lists.ts) | SetFanOut | "My credentials" across every set | v0.3 |
issued | AllSetsIssued (all-sets-lists.ts) | SetFanOut | An issuer's credentials across every set | v0.3 |
recordTypes | RecordTypeService (record-type-service.ts) | active set | Register, list, resolve record types | v0.3 |
issuerAccess | IssuerAccessService (issuer-access-service.ts) | version, roles, credential gateway | Role checks for navigation and page gates | both |
platform | PlatformGovernanceService (platform-governance-service.ts) | credential gateway, its own LogQueryIndex | Pause state, admin snapshot, timelock view and queue, retirements | v0.3 |
disclosure | DisclosureRouter (package-routers.ts) | active and routed DisclosureService | Disclosure trees and disclosure files | v0.3 |
presentation | PresentationRouter (presentation-router.ts) | active and routed PresentationService | Phone codes and challenges | v0.3 |
vc | VcRouter (package-routers.ts) | active and routed VcService | VC and Open Badge checks and export options | v0.3 |
badges | BadgeService (badge-service.ts) | credential gateway, wallet | Standard eddsa-rdfc-2022 proof for Open Badges | v0.3 |
access | AccessService (access-service.ts) | access gateway | Admit, remove, read receipts, submit proofs | v0.3 |
requester | AccessRequesterService (access-requester-service.ts) | wallet, credential gateway, access, worker prover | Make an access identity and a proof in a Web Worker, loading circuit files from /zk | v0.3 |
The v0.2 services exist on a v0.3 build too (they are cheap to construct), but v0.3 pages do not call them, and the reverse holds on a v0.2 build.
Domain service methods
| Service | Methods |
|---|---|
CredentialService | accountNonce, address, checkDocument, checkPackage, checkSignature, getCredential, isAvailable, issue, issuerLineage, signTypedData, supportsRevisions |
StatusService | getStatus, suspend, reinstate, revoke, supersede, supersedeToRegistry |
EnrolmentService | address, createInvitation, signTypedData, redeem, accept, enrol, holderOf, myEnrolment, rebind, unbind, revokeInvitations |
DocumentService | encryptForUpload, upload, openAsIssuer, openFromPackage, openGrant, openCapability, myShareCode, grantAccess, capabilityLink, rotate, removeOldCopies |
RecordTypeService | issuable, register, resolve, setActive, typesOf |
DisclosureService | address, attest, attestPackage, createDisclosure, isFullyVerified, newChallenge, signTypedData, verify |
VcService | checkFile, isFullyVerified, listOptions, verify, verifyBadge |
PresentationService | checkStatic, checkDisclosureCode, isAccepted |
InboxService | myCredentials (from the wallet's enrolment at each issuer) |
IssuedCredentialsService | issuedBy, issuedIds |
PlatformGovernanceService | isPaused, pause, queue, retirements, snapshot, timelockView |
IssuerAccessService | accessOf, issuerName, isIssuer, retiredTo |
AccessService | admit, isAvailable, overview, prepareProof, read, receipts, remove, servedRegistry, submitProof |
AccessRequesterService | identityFromSeeds, newIdentity, prove, walletSeeds |
BadgeService | address, chainId, exportStandard, signTypedData |
RecordService (v0.2) | addRecord, getPublicRecord, getRecordForViewer, getStudentRecords, getStudentRecordsByAddress, getTotalRecords, getUniversityRecords, recordAccess, verifyRecord |
SharingService (v0.2) | shareRecord, unshareRecord, getSharedRecords, isRecordSharedWith, sharedWithMe, sharesOf |
GovernanceService (v0.2) | addAdmin, removeAdmin, getAllAdmins, addCustomRecordType, getTotalCustomTypes, listCustomTypes, isPaused, pauseContract, unpauseContract |
UniversityService (v0.2) | addUniversity, removeUniversity, getAllUniversities, getUniversityName, setUniversityName |
StudentService (v0.2) | getStudentId, registerStudent, migrateStudentWallet |
RoleService (v0.2) | hasRole, isRegisteredUniversity |
The flows that use these methods are described in Flows; the methods' contract calls are in Smart contracts.
Gateways in more detail
v0.2 contract gateway
createContractGateway (src/services/contracts/contract-gateway.ts) offers:
reader(): anAcademicRecordscontract on the public RPC when the address, RPC endpoints and chain id are all configured. Otherwise it falls back to the wallet's signer, and with no wallet it throwsChainConfigError.connected(): the contract bound to the current wallet signer, rebuilt when the signer changes.writer():connected()afterchainGuard().studentRegistry(): theStudentManagementcontract at the addressAcademicRecordsreports.
src/services/contracts/tx.ts holds sendAndWait(pending, onSent), which reports the transaction once it is sent and waits for the receipt, and readEventArg, which reads one argument of an event from a receipt.
v0.3 credential gateway
createCredentialGateway (src/services/credentials/credential-gateway.ts) reads the bundled manifest for the configured chain (src/contracts/v03/manifest.ts). Its main members:
| Member | What it does |
|---|---|
isDeployed() | True when a manifest exists for the chain |
sets() | Every listed set as { label, active, registry } |
forRegistry(address) | A gateway scoped to the set that owns that credential registry, cached; null for an unlisted address |
registry(), deployment() | Address, chain id, deployment block and all contract addresses of the set |
reader(), writer(), statusReader(), statusWriter(), issuerReader(), issuerWriter(), holderReader(), holderWriter(), recordTypeReader(), recordTypeWriter() | Contracts of the set; readers use the public RPC, writers the wallet after chainGuard |
timelockReader() | The chain-wide timelock from the manifest, or null |
logSource() | Event logs over the public RPC, for the indexes |
accountNonce() | The issuer's next signing nonce |
isContractAccount(address) | True when the address has code; an EIP-7702 delegation designator (0xef0100 followed by an address) counts as not a contract |
isValidContractSignature(issuer, hash, signature) | ERC-1271 check (magic value 0x1626ba7e); a call exception or bad data counts as false |
A missing manifest raises CredentialRegistryNotDeployedError. Public reads need NEXT_PUBLIC_RPC_URLS or NEXT_PUBLIC_RPC_URL; without them the gateway throws "Public reads need NEXT_PUBLIC_RPC_URL or NEXT_PUBLIC_RPC_URLS; a wallet-backed read would follow whatever chain the wallet is on". It never falls back to the wallet for reads, because a wallet on another chain would answer for that chain.
Access gateway
createAccessGateway (src/services/credentials/access-gateway.ts) reads the access gate and Semaphore addresses from src/contracts/zk/deployment.<chainId>.json. AccessService.isAvailable() is false when no file exists for the chain, which is how /access decides to show Not on this network yet.
Calling the server
The document service is the only service that calls Certichain's own server. createDocumentService gives it three functions from src/services/document-api.ts (uploadContainer, lookupDocumentCids, removeOtherCopies) and a sign-in context of window.location.host, window.location.origin and the wallet's chain id. Each call goes through withSignIn (src/services/upload.ts): when the server answers 401 or 403, the browser signs in once with the wallet and repeats the request. See Sign-in and sessions.
Optional pieces
| Piece | Built when | Otherwise |
|---|---|---|
v0.2 share history (LogShareIndex) | RPC endpoints, chain id, NEXT_PUBLIC_CONTRACT_ADDRESS and NEXT_PUBLIC_START_BLOCK are all set | SharingService throws ShareHistoryNotConfiguredError for history lists, and the pages say so |
| VC status list support | NEXT_PUBLIC_STATUS_LIST_BASE_URL and NEXT_PUBLIC_STATUS_LIST_PUBLISHER are set | VC exports carry the chain status only |
| Access services | A zk manifest exists for the chain | /access and the access panels say the gate is not on this network |
Conventions
- One composition root. No other file constructs a service with its dependencies. Pages ask for services; they do not build them.
- Errors are thrown, not hidden. A failed chain read throws.
IssuerAccessServicenever turns a failed read into "no role", andSetFanOutfails the whole list if one set cannot be read. - Reads and writes are separate. Readers use the public RPC and work without a wallet. Writers need the wallet and always pass
chainGuardfirst. - Test seam.
ServicesProvideraccepts aservicesprop, andcreateServicesaccepts a fake wallet getter, a fake contract factory and test gateways, so component tests run without a chain.
Source files
src/services/index.tssrc/services/react/services-provider.tsx,src/services/react/browser-services.tssrc/services/contracts/address-book.ts,src/services/contracts/contract-gateway.ts,src/services/contracts/tx.tssrc/services/credentials/credential-gateway.ts,src/services/credentials/access-gateway.tssrc/services/domain/*.tssrc/services/upload.ts,src/services/document-api.tssrc/contracts/v03/manifest.ts
Tests
src/services/index.test.ts,src/services/react/services-provider.test.tsxsrc/services/contracts/address-book.test.ts,src/services/contracts/contract-gateway.test.ts,src/services/contracts/tx.test.tssrc/services/credentials/credential-gateway.test.ts,src/services/credentials/access-gateway.test.ts- One test file per domain service, for example
src/services/domain/credential-service.test.ts,src/services/domain/status-service.test.ts,src/services/domain/document-service.test.ts,src/services/domain/issuer-access-service.test.ts src/services/upload.test.ts,src/services/document-api.test.ts