Managing VDR entries

The VDR specification defines a mechanism for creating, updating, deactivating, and retrieving data from various data sources. These sources are abstracted, enabling a unified integration interface for other systems. A reference implementation of the VDR is available as a library here, and an HTTP binding is also provided within the Cloud Agent.

The purpose of the VDR is to store data used across various SSI protocols. In many use cases, these protocols need to reference external resources using URIs. For example: credential status lists. Since the interface is storage-agnostic, switching the underlying storage implementation is trivial.

VDR is capable of storing arbitrary bytes. In this tutorial, we will create a sample binary data and resolve the VDR to compare those bytes. Then we will try to deactivate the data and observe the resolution failure.

Roles

1. The data owner - is responsible for managing the VDR entries and their lifecycle.

Prerequisites

1. Cloud Agent up and running
2. At least one VDR driver enabled (see below)

Choosing a VDR Driver

The Cloud Agent supports multiple VDR drivers. Each driver stores data differently:

Driver	Enable with	Backend	Use Case
Database	VDR_DATABASE_DRIVER_ENABLED=true	Agent PostgreSQL database	Development and testing
In-memory	VDR_MEMORY_DRIVER_ENABLED=true	Ephemeral memory	Testing only (data lost on restart)
NeoPrism	VDR_NEOPRISM_DRIVER_ENABLED=true	NeoPRISM → Cardano blockchain	Recommended for production
PRISM Node	VDR_PRISM_NODE_DRIVER_ENABLED=true	PRISM Node → Cardano blockchain	Legacy production deployments
PRISM (Blockfrost)	VDR_PRISM_DRIVER_ENABLED=true	Blockfrost → Cardano blockchain	Direct blockchain access

For blockchain-backed storage (NeoPrism, PRISM Node, or PRISM), VDR entries are anchored to the Cardano blockchain via PRISM DID transaction metadata. The DID used by the Cloud Agent must have an active VDR key for signing operations.

Overview

In this example, we will store data using a database driver to enable easy setup and testing. For blockchain-backed VDR with NeoPrism or PRISM Node, see the VDR Interface documentation.

Endpoints

The example uses the following endpoints

Endpoint	Description	Role
GET /vdr/entries	Resolve the data using VDR URI	Anyone
POST /vdr/entries	Create a new VDR entry	Data owner
PUT /vdr/entries	Update an existing VDR entry	Data owner
DELETE /vdr/entries	Delete the VDR entry	Data owner

1. Create a sample binary data to store

echo -ne '\x01\x02\x03\x04' > sample_in.bin

We should have a file named sample_in.bin containing 4 bytes

2. Create a new VDR entry with sample data

curl -X POST "http://localhost:8080/cloud-agent/vdr/entries?drid=database" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @sample_in.bin

The response should look something like

{
  "url": "vdr://?drf=database&drid=database&drv=0.1.0&m=0#d63bdd21-0347-4caf-a255-0cca7c2851fe"
}

The URL is the locator for the VDR entry. If referenced in the SSI protocol, anyone should be able to resolve this data. In this example, we are using a database driver, so the data is resolvable only within the same agent instance.

Note

The VDR URL includes the driver information (drf=database, drid=database) which tells the system which driver to use when resolving this data later. This is why anyone with access to the agent can resolve the data - the URL contains all the necessary information.

3. Resolve the data using VDR URL

Take the URL from previous step and run this command to resolve the URL.

curl -X GET "http://localhost:8080/cloud-agent/vdr/entries?url=<ENCODED_VDR_URL>" > sample_out.bin

Remember to encode the URL using percent encoding to escape any reserved characters in the URL syntax. If executed successfully, the response status should be 200, with the response body saved to a file named sample_out.bin.

4. Compare the VDR entry and the input

diff sample_in.bin sample_out.bin

The output of the diff command should be empty, as the VDR entry is exactly the same as the input data.

5. (Optional) Update the VDR entry

If you need to update the data in an existing VDR entry, create new sample data:

echo -ne '\x05\x06\x07\x08' > updated_sample.bin

Then update the VDR entry:

curl -X PUT "http://localhost:8080/cloud-agent/vdr/entries?url=<ENCODED_VDR_URL>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @updated_sample.bin

The response status should be 200, indicating successful update. The response will include the same VDR URL:

{
  "url": "vdr://?drf=database&drid=database&drv=0.1.0&m=0#d63bdd21-0347-4caf-a255-0cca7c2851fe"
}

You can verify the update by resolving the VDR URL again (step 3) and comparing with updated_sample.bin.

6. Deactivate the VDR entry

curl -X DELETE "http://localhost:8080/cloud-agent/vdr/entries?url=<ENCODED_VDR_URL>"

Similar to resolving the data, we now change the HTTP method to DELETE to deactivate the VDR entry. The response status should be 200, indicating a successful operation.

After trying to resolve the VDR entry in step 3, the response should be

{
  "status": 404,
  "type": "error:VdrServiceError:VdrEntryNotFound",
  "title": "Vdr Entry Not Found",
  "detail": "The data could not be found from a provided URL",
  "instance": "error:instance:b70984a1-71f5-409f-9afc-3b8bada54445"
}

indicating the resource is no longer available for resolution.