> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sphyre.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Contracts

> Base Sepolia smart-contract layer used by Sphyre credential, schema, consent, DID, role, and meta-transaction flows

# Smart Contracts

Sphyre's on-chain layer lives in `fortro-contract-dev/hardhat/contracts` and is consumed by Fortro Engine through ABI files copied into `fortro-engine/src/blockchain/abis`.

<CardGroup cols={2}>
  <Card title="Network" icon="link">
    **Target:** Base Sepolia<br />
    **Chain ID:** `84532`<br />
    **Client:** `ethers` via Fortro Engine
  </Card>

  <Card title="Backend Contract Client" icon="server">
    `fortro-engine/src/blockchain/client.rs` binds to `SSIRegistry.json` and calls the aggregate registry contract.
  </Card>
</CardGroup>

## Contract Inventory

| Contract                 | Purpose                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `SSIRegistry.sol`        | Aggregate registry implementing credential, schema, consent, DID, role, and metadata operations. |
| `CredentialRegistry.sol` | Registers credential hashes, revokes credentials, and exposes registered/revoked checks.         |
| `SchemaRegistry.sol`     | Registers schema hashes, updates schema versions, and exposes schema lookups.                    |
| `ConsentRegistry.sol`    | Grants, revokes, validates, and reads consent records keyed by holder, verifier, and purpose.    |
| `AccessControl.sol`      | Defines `SphyreAccessControl` roles for admin, issuer, holder, verifier, and relayer accounts.   |
| `ERC2771Context.sol`     | Trusted-forwarder context helper for meta-transaction sender resolution.                         |
| `MinimalForwarder.sol`   | EIP-712 style forwarder with nonce, signature verification, and execution support.               |
| `SSIRegistryFactory.sol` | Creates new `SSIRegistry` instances and lists deployed registries.                               |
| `ISSIRegistry.sol`       | Interface covering credential, schema, and consent registry operations.                          |

## Roles

`SphyreAccessControl` defines these role constants:

```text theme={null}
ADMIN_ROLE
ISSUER_ROLE
HOLDER_ROLE
VERIFIER_ROLE
RELAYER_ROLE
```

Credential and schema write operations require issuer authority. Admins manage issuer, holder, verifier, and relayer role assignments.

## Registry Operations

```text theme={null}
registerCredential(did, credentialHash)
revokeCredential(did, credentialHash)
isCredentialRegistered(did, credentialHash)
isCredentialRevoked(did, credentialHash)

registerSchema(schemaId, schemaHash)
getSchemaHash(schemaId)
isSchemaRegistered(schemaId)

grantConsent(userDid, verifierDid, purpose, dataCategories, accessLevel, expiresAt)
revokeConsent(userDid, verifierDid, purpose)
isConsentValid(userDid, verifierDid, purpose)

registerHolderDID(holderDid, holder, didDocCid)
registerIssuerDID(issuerDid, issuer, didDocCid)
registerVerifierDID(verifierDid, verifier, didDocCid)
getDIDInfo(did)
```

## Fortro Engine Routes

The active blockchain API is implemented in `fortro-engine/src/api/blockchain_new.rs`:

```text theme={null}
POST /api/blockchain/credential/register
POST /api/blockchain/credential/revoke
GET  /api/blockchain/credential/check/:did/:credential_hash
POST /api/blockchain/schema/register
POST /api/blockchain/consent/grant
POST /api/blockchain/consent/revoke
GET  /api/blockchain/consent/check/:user_did/:verifier_did/:purpose
GET  /api/blockchain/status
```

`/api/blockchain-legacy` remains mounted for older flows and meta-transaction helper endpoints.

## Configuration

Fortro Engine reads blockchain configuration from environment variables:

```text theme={null}
BLOCKCHAIN_RPC_URL
BLOCKCHAIN_CHAIN_ID
BLOCKCHAIN_DEPLOYER_PRIVATE_KEY
SSI_REGISTRY_ADDRESS
MINIMAL_FORWARDER_ADDRESS
SSI_FACTORY_ADDRESS
```

`BLOCKCHAIN_CHAIN_ID` must match the connected RPC chain. The code validates the chain ID before constructing the contract client.

## Data Anchoring Model

* Credential issuance anchors `credential_hash` against the subject DID.
* Credential revocation checks and revokes the same DID/hash pair.
* Schema creation anchors schema IDs to schema hash/URI values.
* Consent grants and revocations are keyed by holder DID, verifier DID, and purpose.
* Verification flows use on-chain credential registration and revocation checks as one layer of validation.

## Operational Notes

* Backend database state remains the source for rich credential metadata; contracts anchor integrity, status, role, and consent facts.
* Smart-contract calls can fail independently from MongoDB/IPFS writes. Backend handlers log blockchain failure and may continue for selected issuance and revocation flows.
* ABI files must be regenerated and copied into `fortro-engine/src/blockchain/abis` whenever Solidity function signatures change.