diff --git a/documentation/developers/cloud-agent/environment-variables.md b/documentation/developers/cloud-agent/environment-variables.md index a8fd91bbb..df5c43617 100644 --- a/documentation/developers/cloud-agent/environment-variables.md +++ b/documentation/developers/cloud-agent/environment-variables.md @@ -9,88 +9,99 @@ Here is the table with the environment variables sorted in alphabetical order: The following environment variables can be used to configure Identus Cloud Agent (in alphabetical order): -| Variable Name | Description | Type | Default | -|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|-----------------------------------------------| -| ADMIN_TOKEN | Admin token for the admin API key authentication method. | String | admin | -| AGENT_DB_APP_PASSWORD | Agent database application user password for login. | String | password | -| AGENT_DB_APP_USER | Agent database application user for login. | String | agent-application-user | -| AGENT_DB_AWAIT_CONNECTION_THREADS | Number of threads to wait for database connection. | Int | 4 | -| AGENT_DB_HOST | Hostname of the server where the Cloud Agent database is running. | String | localhost | -| AGENT_DB_NAME | Database name where the agent database will store data. | String | agent | -| AGENT_DB_PASSWORD | Agent database password for login. | String | postgres | -| AGENT_DB_PORT | Port of the Cloud Agent database. | Int | 5432 | -| AGENT_DB_USER | Agent database username for login. | String | postgres | -| AGENT_DIDCOMM_PORT | Port on which DIDComm service runs. | Int | 8090 | -| AGENT_HTTP_CLIENT_CONNECTION_POOL_SIZE | Size of the HTTP client connection pool. | Int | 0 | -| AGENT_HTTP_CLIENT_CONNECTION_TIMEOUT | HTTP client connection timeout duration. | String | 5 seconds | -| AGENT_HTTP_CLIENT_IDLE_TIMEOUT | HTTP client idle timeout duration. | String | 5 seconds | -| AGENT_HTTP_PORT | Port on which Cloud Agent runs. | Int | 8085 | -| API_KEY_AUTHENTICATE_AS_DEFAULT_USER | Whether or not to authenticate all API keys as the default user. | Boolean | true | -| API_KEY_AUTO_PROVISIONING | Whether or not to enable auto-provisioning for API keys and register the owner of the api-key automatically. | Boolean | false | -| API_KEY_ENABLED | Whether or not to enable API key authentication. | Boolean | false | -| API_KEY_SALT | Salt used to hash the API key. | String | JLXTS4J2qkMOgfO8 | -| CONNECT_BG_JOB_RECURRENCE_DELAY | Interval at which the background job will try to process connection records. | String | 2 seconds | -| CONNECT_BG_JOB_RECORDS_LIMIT | Maximum number of connection records the background job will try to process at the same time. | Int | 25 | -| CONNECT_DB_APP_PASSWORD | Connect database application user password for login. | String | password | -| CONNECT_DB_APP_USER | Connect database application user for login. | String | connect-application-user | -| CONNECT_DB_AWAIT_CONNECTION_THREADS | Number of threads to wait for database connection. | Int | 4 | -| CONNECT_DB_HOST | Hostname of the server where the Connect database is running. | String | localhost | -| CONNECT_DB_NAME | Database name where the Connect database will store data. | String | connect | -| CONNECT_DB_PASSWORD | Connect database password for login. | String | postgres | -| CONNECT_DB_PORT | Port of the Connect database. | Int | 5432 | -| CONNECT_DB_USER | Connect database username for login. | String | postgres | -| CONNECT_INVITATION_EXPIRY | The connect invitation expiry duration e.g 300 seconds. After which the OOB Connect Invitation will expire. | String | 300 seconds | -| CREDENTIAL_LEEWAY | Time leeway when verifying credential dates; if the time difference is less than the leeway, the credential will still be considered valid. | String | 0 seconds | -| CREDENTIAL_SD_JWT_EXPIRY | Expiry duration for SD-JWT credentials. | String | 30 days | -| CREDENTIAL_VERIFY_DATES | Whether or not to verify credential dates (expiration). | Boolean | false | -| CREDENTIAL_VERIFY_SIGNATURE | Whether or not to verify a credential signature. | Boolean | true | -| DEFAULT_JWT_VC_OFFER_DOMAIN | Default domain for JWT VC offers. Must be set to the value of the Cloud Agent endpoint. | String | default-domain | -| DEFAULT_KAFKA_ENABLED | Whether or not to enable Kafka integration. | Boolean | false | -| DEFAULT_WALLET_AUTH_API_KEY | The authentication API key to be used for default entity that uses default wallet. | String | default | -| DEFAULT_WALLET_ENABLED | Whether or not to initialize the default wallet. | Boolean | true | -| DEFAULT_WALLET_SEED | The BIP32 wallet seed to be used for default wallet represented by a hexadecimal string. | String | Null | -| DEFAULT_WALLET_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for the default wallet webhook. | String | Null | -| DEFAULT_WALLET_WEBHOOK_URL | The default wallet webhook endpoint URL to which notifications will be sent. | String | Null | -| DID_STATE_SYNC_TRIGGER_RECURRENCE_DELAY | Triggering DID state sync delay in Hocon duration format. | String | 30 seconds | -| DIDCOMM_SERVICE_URL | URL of the DIDComm server that also runs for this agent. | String | http://localhost:8090 | -| ENABLE_ANONCRED | Enable support for the AnonCred credential type via API and DIDComm. | Boolean | false | -| GLOBAL_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for the global wallet webhook. | String | Null | -| GLOBAL_WEBHOOK_URL | The global webhook endpoint URL to which notifications will be sent. | String | Null | -| ISSUANCE_INVITATION_EXPIRY | The issuance invitation expiry duration e.g 300 seconds. After which the OOB Credential Offer will expire. | String | 300 seconds | -| KEYCLOAK_CLIENT_ID | The Keycloak client ID. | String | `prism-agent` | -| KEYCLOAK_CLIENT_SECRET | The Keycloak client secret. | String | `prism-agent-demo-secret` | -| KEYCLOAK_ENABLED | Whether or not to enable Keycloak authentication and authorisation. | Boolean | false | -| KEYCLOAK_REALM | The Keycloak realm name. | String | `atala-demo` | -| KEYCLOAK_URL | The Keycloak server URL. | String | http://localhost:9980 | -| KEYCLOAK_UMA_AUTO_UPGRADE_RPT | Whether or not to enable automatic upgrade of RPT tokens. If disabled, `accessToken` must be RPT and include the permission claims. | Boolean | true | -| KEYCLOAK_ROLES_CLAIM_PATH | The json path to the `roles` claim in the JWT payload. Used for role-based authorization (e.g. admin or tenant). | String | `resource_access..roles` | -| LOG_LEVEL | Cloud Agent log level. The default log level is INFO. Possible values: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`. Values are case-insensitive. | String | `INFO` | -| POLLUX_DB_APP_PASSWORD | Pollux database application user password for login. | String | password | -| POLLUX_DB_APP_USER | Pollux database application user for login. | String | pollux-application-user | -| POLLUX_DB_AWAIT_CONNECTION_THREADS | Number of threads to wait for database connection. | Int | 4 | -| POLLUX_DB_HOST | Hostname of the server where the Pollux database is running. | String | localhost | -| POLLUX_DB_NAME | Database name where the Pollux database will store data. | String | pollux | -| POLLUX_DB_PASSWORD | Pollux database password for login. | String | postgres | -| POLLUX_DB_PORT | Port of the Pollux database. | Int | 5432 | -| POLLUX_DB_USER | Pollux database username for login. | String | postgres | -| POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL | URL of the status list registry used to verify the revocation of JWT credentials. | String | http://localhost:8085 | -| PRESENTATION_INVITATION_EXPIRY | The presentation invitation expiry duration e.g 300 seconds. After which the OOB Request Presentation will expire. | String | 300 seconds | -| PRESENTATION_LEEWAY | Time leeway when verifying challenge dates. | String | 0 seconds | -| PRESENTATION_VERIFY_DATES | Whether or not to verify challenge dates during presentation. | Boolean | false | -| PRESENTATION_VERIFY_HOLDER_BINDING | Whether or not to verify holder binding when verifying presentations (ensures the presenter is the holder). | Boolean | false | -| PRESENTATION_VERIFY_SIGNATURE | Whether or not to verify the signature of a challenge used during credential presentation. | Boolean | true | -| PRISM_NODE_HOST | Hostname of the server where the Prism Node is running. | String | localhost | -| PRISM_NODE_PORT | Port of the Prism Node. | Int | 50053 | -| PRISM_NODE_USE_PLAIN_TEXT | Whether or not to use plain text for Prism Node communication gRPC protocol. | Boolean | true | -| REST_SERVICE_URL | URL of the REST service. | String | https://host.docker.internal:8080/cloud-agent | -| SECRET_STORAGE_BACKEND | Secret storage backend for keys and credentials. If Vault is used, the Vault server must be running; otherwise, a database can be used for development purposes only. | Enum(vault, postgres) | vault | -| STATUS_LIST_SYNC_TRIGGER_RECURRENCE_DELAY | Triggering status list revocation sync for revoked credentials delay in Hocon duration format. | String | 30 seconds | -| VAULT_ADDR | URL of the vault service for Cloud Agent to use for secret management. | String | http://localhost:8200 | -| VAULT_APPROLE_ROLE_ID | The `role_id` for HashiCorp Vault authentication with AppRole | String | Null | -| VAULT_APPROLE_SECRET_ID | The `secret_id` for HashiCorp Vault authentication with AppRole | String | Null | -| VAULT_TOKEN | Vault service auth token. | String | Null | -| VAULT_USE_SEMANTIC_PATH | Enable full path convention for vault secret path. | Boolean | true | -| WEBHOOK_PARALLELISM | Maximum number of events that will be retrieved in a single iteration from the event queue by the webhook publisher. | Int | Null | +| Variable Name | Description | Type | Default | +|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|-----------------------------------------------| +| ADMIN_TOKEN | Admin token for the admin API key authentication method. | String | admin | +| AGENT_DB_APP_PASSWORD | Agent database application user password for login. | String | password | +| AGENT_DB_APP_USER | Agent database application user for login. | String | agent-application-user | +| AGENT_DB_AWAIT_CONNECTION_THREADS | Number of threads to wait for database connection. | Int | 4 | +| AGENT_DB_HOST | Hostname of the server where the Cloud Agent database is running. | String | localhost | +| AGENT_DB_NAME | Database name where the agent database will store data. | String | agent | +| AGENT_DB_PASSWORD | Agent database password for login. | String | postgres | +| AGENT_DB_PORT | Port of the Cloud Agent database. | Int | 5432 | +| AGENT_DB_USER | Agent database username for login. | String | postgres | +| AGENT_DIDCOMM_PORT | Port on which DIDComm service runs. | Int | 8090 | +| AGENT_HTTP_CLIENT_CONNECTION_POOL_SIZE | Size of the HTTP client connection pool. | Int | 0 | +| AGENT_HTTP_CLIENT_CONNECTION_TIMEOUT | HTTP client connection timeout duration. | String | 5 seconds | +| AGENT_HTTP_CLIENT_IDLE_TIMEOUT | HTTP client idle timeout duration. | String | 5 seconds | +| AGENT_HTTP_PORT | Port on which Cloud Agent runs. | Int | 8085 | +| API_KEY_AUTHENTICATE_AS_DEFAULT_USER | Whether or not to authenticate all API keys as the default user. | Boolean | true | +| API_KEY_AUTO_PROVISIONING | Whether or not to enable auto-provisioning for API keys and register the owner of the api-key automatically. | Boolean | false | +| API_KEY_ENABLED | Whether or not to enable API key authentication. | Boolean | false | +| API_KEY_SALT | Salt used to hash the API key. | String | JLXTS4J2qkMOgfO8 | +| CONNECT_BG_JOB_RECURRENCE_DELAY | Interval at which the background job will try to process connection records. | String | 2 seconds | +| CONNECT_BG_JOB_RECORDS_LIMIT | Maximum number of connection records the background job will try to process at the same time. | Int | 25 | +| CONNECT_DB_APP_PASSWORD | Connect database application user password for login. | String | password | +| CONNECT_DB_APP_USER | Connect database application user for login. | String | connect-application-user | +| CONNECT_DB_AWAIT_CONNECTION_THREADS | Number of threads to wait for database connection. | Int | 4 | +| CONNECT_DB_HOST | Hostname of the server where the Connect database is running. | String | localhost | +| CONNECT_DB_NAME | Database name where the Connect database will store data. | String | connect | +| CONNECT_DB_PASSWORD | Connect database password for login. | String | postgres | +| CONNECT_DB_PORT | Port of the Connect database. | Int | 5432 | +| CONNECT_DB_USER | Connect database username for login. | String | postgres | +| CONNECT_INVITATION_EXPIRY | The connect invitation expiry duration e.g 300 seconds. After which the OOB Connect Invitation will expire. | String | 300 seconds | +| CREDENTIAL_LEEWAY | Time leeway when verifying credential dates; if the time difference is less than the leeway, the credential will still be considered valid. | String | 0 seconds | +| CREDENTIAL_SD_JWT_EXPIRY | Expiry duration for SD-JWT credentials. | String | 30 days | +| CREDENTIAL_VERIFY_DATES | Whether or not to verify credential dates (expiration). | Boolean | false | +| CREDENTIAL_VERIFY_SIGNATURE | Whether or not to verify a credential signature. | Boolean | true | +| DEFAULT_JWT_VC_OFFER_DOMAIN | Default domain for JWT VC offers. Must be set to the value of the Cloud Agent endpoint. | String | default-domain | +| DEFAULT_KAFKA_ENABLED | Whether or not to enable Kafka integration. | Boolean | false | +| DEFAULT_WALLET_AUTH_API_KEY | The authentication API key to be used for default entity that uses default wallet. | String | default | +| DEFAULT_WALLET_ENABLED | Whether or not to initialize the default wallet. | Boolean | true | +| DEFAULT_WALLET_SEED | The BIP32 wallet seed to be used for default wallet represented by a hexadecimal string. | String | Null | +| DEFAULT_WALLET_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for the default wallet webhook. | String | Null | +| DEFAULT_WALLET_WEBHOOK_URL | The default wallet webhook endpoint URL to which notifications will be sent. | String | Null | +| DID_STATE_SYNC_TRIGGER_RECURRENCE_DELAY | Triggering DID state sync delay in Hocon duration format. | String | 30 seconds | +| DIDCOMM_SERVICE_URL | URL of the DIDComm server that also runs for this agent. | String | http://localhost:8090 | +| ENABLE_ANONCRED | Enable support for the AnonCred credential type via API and DIDComm. | Boolean | false | +| GLOBAL_WEBHOOK_API_KEY | The optional API key (bearer token) to use as the Authorization header for the global wallet webhook. | String | Null | +| GLOBAL_WEBHOOK_URL | The global webhook endpoint URL to which notifications will be sent. | String | Null | +| ISSUANCE_INVITATION_EXPIRY | The issuance invitation expiry duration e.g 300 seconds. After which the OOB Credential Offer will expire. | String | 300 seconds | +| KEYCLOAK_CLIENT_ID | The Keycloak client ID. | String | `prism-agent` | +| KEYCLOAK_CLIENT_SECRET | The Keycloak client secret. | String | `prism-agent-demo-secret` | +| KEYCLOAK_ENABLED | Whether or not to enable Keycloak authentication and authorisation. | Boolean | false | +| KEYCLOAK_REALM | The Keycloak realm name. | String | `atala-demo` | +| KEYCLOAK_URL | The Keycloak server URL. | String | http://localhost:9980 | +| KEYCLOAK_UMA_AUTO_UPGRADE_RPT | Whether or not to enable automatic upgrade of RPT tokens. If disabled, `accessToken` must be RPT and include the permission claims. | Boolean | true | +| KEYCLOAK_ROLES_CLAIM_PATH | The json path to the `roles` claim in the JWT payload. Used for role-based authorization (e.g. admin or tenant). | String | `resource_access..roles` | +| LOG_LEVEL | Cloud Agent log level. The default log level is INFO. Possible values: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`. Values are case-insensitive. | String | `INFO` | +| POLLUX_DB_APP_PASSWORD | Pollux database application user password for login. | String | password | +| POLLUX_DB_APP_USER | Pollux database application user for login. | String | pollux-application-user | +| POLLUX_DB_AWAIT_CONNECTION_THREADS | Number of threads to wait for database connection. | Int | 4 | +| POLLUX_DB_HOST | Hostname of the server where the Pollux database is running. | String | localhost | +| POLLUX_DB_NAME | Database name where the Pollux database will store data. | String | pollux | +| POLLUX_DB_PASSWORD | Pollux database password for login. | String | postgres | +| POLLUX_DB_PORT | Port of the Pollux database. | Int | 5432 | +| POLLUX_DB_USER | Pollux database username for login. | String | postgres | +| POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL | URL of the status list registry used to verify the revocation of JWT credentials. | String | http://localhost:8085 | +| PRESENTATION_INVITATION_EXPIRY | The presentation invitation expiry duration e.g 300 seconds. After which the OOB Request Presentation will expire. | String | 300 seconds | +| PRESENTATION_LEEWAY | Time leeway when verifying challenge dates. | String | 0 seconds | +| PRESENTATION_VERIFY_DATES | Whether or not to verify challenge dates during presentation. | Boolean | false | +| PRESENTATION_VERIFY_HOLDER_BINDING | Whether or not to verify holder binding when verifying presentations (ensures the presenter is the holder). | Boolean | false | +| PRESENTATION_VERIFY_SIGNATURE | Whether or not to verify the signature of a challenge used during credential presentation. | Boolean | true | +| PRISM_NODE_HOST | Hostname of the server where the Prism Node is running. | String | localhost | +| PRISM_NODE_PORT | Port of the Prism Node. | Int | 50053 | +| PRISM_NODE_USE_PLAIN_TEXT | Whether or not to use plain text for Prism Node communication gRPC protocol. | Boolean | true | +| REST_SERVICE_URL | URL of the REST service. | String | https://host.docker.internal:8080/cloud-agent | +| SECRET_STORAGE_BACKEND | Secret storage backend for keys and credentials. If Vault is used, the Vault server must be running; otherwise, a database can be used for development purposes only. | Enum(vault, postgres) | vault | +| STATUS_LIST_SYNC_TRIGGER_RECURRENCE_DELAY | Triggering status list revocation sync for revoked credentials delay in Hocon duration format. | String | 30 seconds | +| VAULT_ADDR | URL of the vault service for Cloud Agent to use for secret management. | String | http://localhost:8200 | +| VAULT_APPROLE_ROLE_ID | The `role_id` for HashiCorp Vault authentication with AppRole | String | Null | +| VAULT_APPROLE_SECRET_ID | The `secret_id` for HashiCorp Vault authentication with AppRole | String | Null | +| VAULT_TOKEN | Vault service auth token. | String | Null | +| VAULT_USE_SEMANTIC_PATH | Enable full path convention for vault secret path. | Boolean | true | +| VDR_DATABASE_DRIVER_ENABLED | Whether or not to enable the database VDR driver. | Boolean | false | +| VDR_MEMORY_DRIVER_ENABLED | Whether or not to enable the in-memory VDR driver. | Boolean | false | +| VDR_PRISM_DRIVER_BLOCKFROST_API_KEY | Blockfrost API key for public Blockfrost service. Mutually exclusive with private network configuration. | String | Null | +| VDR_PRISM_DRIVER_DID_PRISM | DID that will own the data. The DID should have an active VDR key. | String | Null | +| VDR_PRISM_DRIVER_ENABLED | Whether or not to enable the Prism VDR driver. Corresponding Prism driver configuration must be set if this driver is enabled. | Boolean | false | +| VDR_PRISM_DRIVER_INDEX_INTERVAL_SECOND | Indexer polling interval in seconds for the Prism VDR driver. | Int | 60 | +| VDR_PRISM_DRIVER_PRIVATE_NETWORK_PROTOCOL_MAGIC | Protocol magic number for private network Blockfrost instance. Must not be present if Blockfrost API key is provided. | Int | Null | +| VDR_PRISM_DRIVER_PRIVATE_NETWORK_URL | Private network URL for local/private Blockfrost instance. Must not be present if Blockfrost API key is provided. | String | Null | +| VDR_PRISM_DRIVER_VDR_PRIVATE_KEY | VDR private key for the Prism driver. Must not be present if Blockfrost API key is provided. | String | Null | +| VDR_PRISM_DRIVER_VDR_STATE_DIR | State directory path for the VDR indexer. | String | Null | +| VDR_PRISM_DRIVER_WALLET_MNEMONIC | Wallet mnemonic phrase for DID configuration in the Prism driver. Must not be present if Blockfrost API key is provided. | String | Null | +| WEBHOOK_PARALLELISM | Maximum number of events that will be retrieved in a single iteration from the event queue by the webhook publisher. | Int | Null | ## Hocon duration format diff --git a/documentation/developers/cloud-agent/vdr.md b/documentation/developers/cloud-agent/vdr.md index 4fa00ec5e..a2003a173 100644 --- a/documentation/developers/cloud-agent/vdr.md +++ b/documentation/developers/cloud-agent/vdr.md @@ -1,4 +1,6 @@ -# VDR +# VDR Interface + +## Overview VDR is an interface for performing CRUD and verification operations on a generic data storage driver. The specification is available [here](https://github.com/hyperledger-identus/vdr), @@ -6,12 +8,12 @@ along with a reference implementation provided as a library. The interface defines simple create, read, update, delete, and verify operations, delegating their execution to an underlying driver. Driver is an actual implementation of a data storage mechanism. -## HTTP binding +## HTTP Binding -Although the VDR implementation is available as a library, it is also integrated intothe Cloud Agent +Although the VDR implementation is available as a library, it is also integrated into the Cloud Agent to expose its functionality via HTTP, supporting use cases where direct library integration is not feasible. -The Cloud Agent exposes the VDR functionality through a RESTful stlye API, +The Cloud Agent exposes the VDR functionality through a RESTful style API, providing an interface analogous to direct method calls. __Example__ @@ -23,7 +25,7 @@ __Example__ | `update(url, data, options)` | `PUT /vdr/entries?url=...` | | `delete(url, options)` | `DELETE /vdr/entries?url=...` | -## Selecting VDR drivers +## Selecting VDR Drivers The driver is a key component of VDR, providing the actual implementation for the storage backend. The cloud agent acts as a proxy, supporting multiple drivers and allowing users to choose the one that best fits their needs. @@ -32,14 +34,184 @@ To select the appropriate driver, specify the following parameters when creating | Parameters | Description | |-|-| | `drid` | Driver ID | -| `drf` | Driver famely | +| `drf` | Driver family | | `drv` | Driver version | -Currently, the Cloud Agent supports the following drivers +For a full range of parameters and driver options, please refer to the [VDR specification](https://github.com/hyperledger-identus/vdr). + +## Available Drivers + +The Cloud Agent supports multiple VDR drivers for different use cases: + +| Driver | ID | Family | Version | Description | Use Case | +|--------|----|----|---------|-------------|----------| +| In-memory | `memory` | `memory` | `0.1.0` | Ephemeral in-memory storage | Testing, non-persistent data | +| Database | `database` | `database` | `0.1.0` | Local database storage | Development, testing | +| PRISM | `PRISMDriverInMemory` | `PRISM` | `1.0` | Cardano blockchain storage | Blockchain-backed, public verification | + +### Driver Configuration + +**Memory Driver**: Enable with `VDR_MEMORY_DRIVER_ENABLED=true`. No additional configuration required. + +**Database Driver**: Enable with `VDR_DATABASE_DRIVER_ENABLED=true`. Uses the Cloud Agent's existing database configuration. + +**PRISM Driver**: See the [PRISM Driver](#prism-driver) section below. + +For all VDR environment variables, see the [Environment Variables](./environment-variables.md) documentation. + +**Choosing a driver**: +- **Development/Testing**: Use `memory` or `database` drivers for fast iteration without blockchain overhead +- **Blockchain-backed storage**: Use `PRISM` driver for decentralized, permanent, publicly verifiable storage + +## PRISM Driver + +### Overview + +The PRISM driver stores data on the Cardano blockchain, providing decentralized, permanent, and verifiable storage. Unlike the in-memory and database drivers which store data locally for testing, the PRISM driver offers blockchain-backed guarantees suitable for deployments requiring blockchain permanence. + +**Key capabilities**: +- Data stored on Cardano blockchain, not controlled by any single entity +- Permanent, immutable storage that persists beyond agent lifecycle +- Publicly verifiable by anyone with blockchain access +- Designed for scenarios requiring blockchain auditability + +**Best suited for**: +- Deployments requiring public, decentralized verification +- Credential status lists that must remain accessible indefinitely +- Use cases with regulatory requirements for tamper-proof storage + +**For development**: Use the in-memory or database drivers for faster iteration without blockchain transaction costs and delays. + +### Prerequisites + +Before enabling the PRISM driver, ensure you have: + +1. **Active PRISM DID**: A `did:prism:` identifier with an active VDR key +2. **Cardano Wallet**: A wallet mnemonic phrase (24 words) for blockchain transactions +3. **VDR Private Key**: A Secp256k1 private key (in hexadecimal format) of an active VDR key of the DID +4. **Blockfrost Access**: Either: + - A Blockfrost API key for public networks (mainnet, preprod, preview), OR + - A private Blockfrost instance URL and protocol magic number +5. **State Directory**: A filesystem directory with read/write permissions for the indexed VDR state + +### Configuration + +Configure the PRISM driver using these environment variables: + +#### Core Configuration + +| Variable | Required? | Description | Example/Default | +|----------|-----------|-------------|-----------------| +| `VDR_PRISM_DRIVER_ENABLED` | ✅ Yes | Enable the PRISM VDR driver | `true` | +| `VDR_PRISM_DRIVER_DID_PRISM` | ✅ Yes | DID that owns the data (must have active VDR key) | `did:prism:abc123...` | +| `VDR_PRISM_DRIVER_VDR_PRIVATE_KEY` | ✅ Yes | VDR private key in hexadecimal format | `a1b2c3d4e5f6...` | +| `VDR_PRISM_DRIVER_WALLET_MNEMONIC` | ✅ Yes | Wallet mnemonic phrase (space-separated, 24 words) | `word1 word2 ... word24` | +| `VDR_PRISM_DRIVER_VDR_STATE_DIR` | ✅ Yes | Directory path for indexer state storage | `/var/lib/cloud-agent/vdr-state` | + +#### Network Configuration (choose ONE) + +| Variable | Required? | Description | Example/Default | +|----------|-----------|-------------|-----------------| +| `VDR_PRISM_DRIVER_BLOCKFROST_API_KEY` | Option A | Your Blockfrost API key (mainnet/preprod/preview) | `mainnetABC123...` | +| `VDR_PRISM_DRIVER_PRIVATE_NETWORK_URL` | Option B | URL of private Blockfrost instance | `http://localhost:18082` | +| `VDR_PRISM_DRIVER_PRIVATE_NETWORK_PROTOCOL_MAGIC` | Option B | Protocol magic number for private network | `42` | + +**⚠️ Network Configuration**: You MUST configure exactly ONE network option: +- **Option A** (Public Blockfrost): Set `VDR_PRISM_DRIVER_BLOCKFROST_API_KEY` only +- **Option B** (Private Network): Set both `VDR_PRISM_DRIVER_PRIVATE_NETWORK_URL` and `VDR_PRISM_DRIVER_PRIVATE_NETWORK_PROTOCOL_MAGIC` + +The Cloud Agent will reject configurations that set both options simultaneously. + +#### Optional Configuration + +| Variable | Required? | Description | Example/Default | +|----------|-----------|-------------|-----------------| +| `VDR_PRISM_DRIVER_INDEX_INTERVAL_SECOND` | No | Blockchain polling interval (seconds) | `60` (default) | + +### Configuration Examples + +#### Example 1: Public Blockfrost (Mainnet) + +This example shows a mainnet configuration using Blockfrost's mainnet service: + +```bash +export VDR_PRISM_DRIVER_ENABLED=true +export VDR_PRISM_DRIVER_BLOCKFROST_API_KEY="mainnetABC123YourKeyHere" +export VDR_PRISM_DRIVER_DID_PRISM="did:prism:4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b" +export VDR_PRISM_DRIVER_VDR_PRIVATE_KEY="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2" +export VDR_PRISM_DRIVER_WALLET_MNEMONIC="word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 word16 word17 word18 word19 word20 word21 word22 word23 word24" +export VDR_PRISM_DRIVER_VDR_STATE_DIR="/var/lib/cloud-agent/vdr-state" +export VDR_PRISM_DRIVER_INDEX_INTERVAL_SECOND=60 +``` + +#### Example 2: Private Network + +This example shows a configuration for a private or local Cardano network: + +```bash +export VDR_PRISM_DRIVER_ENABLED=true +export VDR_PRISM_DRIVER_PRIVATE_NETWORK_URL="http://localhost:18082" +export VDR_PRISM_DRIVER_PRIVATE_NETWORK_PROTOCOL_MAGIC=42 +export VDR_PRISM_DRIVER_DID_PRISM="did:prism:4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b" +export VDR_PRISM_DRIVER_VDR_PRIVATE_KEY="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2" +export VDR_PRISM_DRIVER_WALLET_MNEMONIC="word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 word16 word17 word18 word19 word20 word21 word22 word23 word24" +export VDR_PRISM_DRIVER_VDR_STATE_DIR="/var/lib/cloud-agent/vdr-state" +``` + +### Driver Variants + +**⚠️ Cloud Agent Users**: The Cloud Agent is configured to use `PRISMDriverInMemory` ONLY. This is the sole PRISM driver implementation available via the Cloud Agent's HTTP API. + +The underlying [PRISM VDR driver library](https://github.com/hyperledger-identus/prism-vdr-driver) provides three implementations with different storage backends: + +#### 1. PRISMDriverInMemory ✅ Available in Cloud Agent + +- **Storage**: In-memory state with chunk file persistence +- **Use case**: Standard Cloud Agent deployment, balances performance with persistence +- **Configuration**: Via environment variables documented in the [Configuration](#configuration) section above +- **State management**: Loads blockchain state from chunk files in the configured state directory +- **Source code**: [PRISMDriverInMemory.scala](https://github.com/hyperledger-identus/prism-vdr-driver/blob/main/src/main/scala/hyperledger/identus/vdr/prism/PRISMDriverInMemory.scala), [PrismDriver.scala](https://github.com/hyperledger-identus/prism-vdr-driver/blob/main/src/main/scala/hyperledger/identus/vdr/prism/PrismDriver.scala) + +#### 2. PRISMDriverMongoDB ❌ Library Integration Only + +- **Storage**: MongoDB (read-only) +- **Use case**: Applications requiring shared, scalable state storage across multiple instances +- **Requires**: Direct Scala library integration, external MongoDB setup and indexing +- **NOT available**: Cannot be used via Cloud Agent's HTTP API +- **Source code**: [PRISMDriverMongoDB.scala](https://github.com/hyperledger-identus/prism-vdr-driver/blob/main/src/main/scala/hyperledger/identus/vdr/prism/PRISMDriverMongoDB.scala) + +#### 3. PRISMDriverMongoDBWithIndexer ❌ Library Integration Only + +- **Storage**: MongoDB with built-in indexing capability +- **Use case**: Applications that need to manage their own blockchain indexing process +- **Requires**: Direct Scala library integration, external MongoDB setup +- **NOT available**: Cannot be used via Cloud Agent's HTTP API +- **Source code**: [PRISMDriverMongoDBWithIndexer.scala](https://github.com/hyperledger-identus/prism-vdr-driver/blob/main/src/main/scala/hyperledger/identus/vdr/prism/PRISMDriverMongoDBWithIndexer.scala) + +#### Comparison Table + +| Implementation | Storage Backend | Cloud Agent | Library Integration | +|----------------|-----------------|-------------|---------------------| +| PRISMDriverInMemory | In-memory + chunk files | ✅ Available | ✅ Available | +| PRISMDriverMongoDB | MongoDB (read-only) | ❌ Not available | ✅ Available | +| PRISMDriverMongoDBWithIndexer | MongoDB + indexing | ❌ Not available | ✅ Available | + +All implementations share the same protocol parameters: +- **Driver Family**: `PRISM` +- **Driver Version**: `1.0` + +**For Cloud Agent users**: Use the environment variables documented above. The `PRISMDriverInMemory` implementation is automatically configured when you enable the PRISM driver. + +**For library integrators**: If you need MongoDB-backed storage, you must integrate the PRISM VDR driver library directly into your Scala application. Refer to the driver source code and library documentation for integration details. + +### Important Considerations + +**Security**: Store your wallet mnemonic and VDR private key securely. Never commit these values to version control or expose them in logs. Consider using secret management solutions like HashiCorp Vault in operational environments. + +**State Directory**: Ensure the state directory has appropriate permissions and sufficient disk space. The indexer will create required subdirectories automatically on first run. + +**Blockchain Data Permanence**: Data stored on the blockchain is permanent and cannot be truly deleted. The VDR `DELETE` operation marks entries as deactivated but does not remove them from the blockchain. Plan your data lifecycle accordingly and avoid storing sensitive information that may need to be removed. -| Driver | ID | Family | Version | Description | -|-|-|-|-|-| -| In-memory | `memory` | `memory` | `0.1.0` | Driver storing data in-memory for testing | -| Database | `database` | `database` | `0.1.0` | Driver storing data in local database testing purposes | +**Transaction Costs**: Writing data to the Cardano blockchain incurs transaction fees paid from your configured wallet. Ensure the wallet has sufficient ADA balance for your expected operations. -For a full range of parameters and driver options, please refer the the [VDR specification](https://github.com/hyperledger-identus/vdr). +**Indexing Delay**: Changes to the blockchain may take time to be reflected in the driver's state, depending on the configured polling interval and blockchain confirmation times. Consider these delays when designing time-sensitive workflows.