The Problem That Started Everything
Picture a tailor in Oshodi Market who has sewn uniforms for three secondary schools, completed dozens of referral jobs from satisfied customers, and run a small cooperative savings group for four years. She is reliable. She delivers. She has a track record that any lender or partner would want to see.
But none of it is portable.
Her reputation lives in the memory of the people around her. Her savings group records exist in a notebook. Her relationship with the schools is a handshake agreement renewed each term. The moment she walks outside her immediate community to access a loan, apply for a larger contract, or join a new cooperative in another city, she starts from zero. She has to prove herself again, from nothing, to people who have no reason to trust her yet.
This is not a story about one tailor. It is the structural condition of hundreds of millions of people across the African informal economy. Skills, relationships, track records, contributions to community systems, all of it is locked inside local context and cannot travel.
Zivana Protocol is being built to change that. The core premise is simple: everything owned by informal actors must travel with them. Their identity, their credentials, their proven contributions, these should be anchored in infrastructure they control, not in a database owned by a platform that can revoke access, go offline, or exclude them on a whim.
That premise leads directly to a technical requirement: decentralized, self-sovereign identity. And delivering that on real infrastructure, not a proof of concept, is what VAL-003 is about.
What Zivana Is Building and Why Identity Is Central
Zivana Protocol is an open Layer 2 trust infrastructure protocol being built on Cardano and Midnight for the African informal economy. It is currently in Phase 0: Foundation Verification, which means proving that every stack component works correctly before any protocol logic is built on top.
The protocol is not an app. It is infrastructure, the kind of infrastructure that allows a cooperative in Lagos, a savings group in Accra, and a skills network in Nairobi to issue verifiable credentials to their members, and for those credentials to be recognised and verified by anyone, anywhere, without requiring a phone call to the issuing institution.
For this to work, the identity layer must be:
Decentralized. No single company controls who can issue or verify credentials.
Self-sovereign. The credential holder controls their own identity and decides what to share with whom.
Verifiable. Any third party can independently confirm that a credential is genuine, without contacting the issuer.
Anchored on a public ledger. The identity record must exist somewhere tamper-proof and permanent.
Cardano preprod is the ledger for our testing environment. The Hyperledger Identus stack is the identity infrastructure we are verifying. VAL-003 was the exercise that proved the full pipeline works end-to-end, from DID publication on-chain to credential issuance to independent verification.
What VAL-003 Proved
VAL-003 ran three independent Identus Cloud Agent stacks, one for the issuer, one for the holder, one for the verifier, communicating over DIDComm V2 across separate Docker networks, all connected to a real Cardano preprod node.
Here is what was confirmed, with verifiable evidence:
1. DID published on Cardano preprod
A PRISM DID was created, published, and confirmed on the Cardano preprod blockchain. This is not a simulated event. A real transaction was submitted through a funded Cardano wallet, a real fee was paid, and the DID operation was indexed by a real db-sync instance reading the chain.
DID:
did:prism:1e99b05986e260d569eea85c181af04fb8f7e437d337677b609b79e260fd3292Transaction:
f6becc5272cf26a328c5d822390a5fee68a769bc23b26e3fcf11f8e075688389Block: 4,894,745 | Slot: 127,424,674
Fee paid: 183,365 lovelace — the wallet balance decreased from 10,000,000,000, confirming the transaction was real
2. JWT credential issued end-to-end
A W3C Verifiable Credential in JWT format was issued by the issuer agent to the holder agent over a live DIDComm V2 connection. The credential contained real claims (role: contributor, jurisdiction: NG), a registered schema, and a resolvable credential status URL for revocation checking.
3. Presentation verified by an independent verifier
The holder presented the credential to a separate verifier agent. The verifier resolved the issuer's DID from the Cardano preprod chain, verified the JWT signature, checked the credential status, and returned PresentationVerified.
This last step is the one that matters most for Zivana's use case. It proves that a third party, one that has never interacted with the issuer, can independently confirm that a credential is genuine, using only the public Cardano blockchain as the source of truth.
What It Actually Took: The Engineering Reality
This section is for builders. Running Hyperledger Identus on real Cardano infrastructure is not straightforward. The documentation covers the happy path. The production path has several critical gaps that are not documented anywhere. We are publishing these findings so that other teams building on Identus do not spend weeks rediscovering them.
Finding 1: NODE_LEDGER=cardano is not the default
This is the most important finding in this entire post.
The prism-node application defaults to ledger = "in-memory" in its bundled application.conf. Without explicitly setting NODE_LEDGER=cardano in your environment, prism-node will report DID operations as PUBLISHED without ever submitting a transaction to the Cardano network. The wallet balance will not change. The blockchain will not have any record of your DID.
We ran for several hours, believing DIDs had been published on-chain because the Cloud Agent API returned "status": "PUBLISHED". In reality, every publication was in-memory only. The proof was in the wallet: exactly 10,000,000,000 lovelace, one incoming transaction, zero outgoing. Nothing had touched the chain.
Adding NODE_LEDGER=cardano The prism-node environment caused the first real Cardano transaction to be submitted immediately. The wallet balance dropped by 183,365 lovelaces.
Finding 2: NODE_CARDANO_NETWORK must be testnet, not preprod
The NODE_CARDANO_NETWORK environment variable in prism-node v2.6.0 accepts only two values: Testnet or Mainnet. The string preprod causes a NoSuchElementException Crash at startup. Preprod is a Cardano testnet environment, so the correct value is testnet.
This is not documented in the Identus setup guides at the time of writing.
Finding 3: POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL controls credential status URLs
When a JWT credential is issued, the Cloud Agent embeds a status list URL into the credential for revocation checking. This URL is controlled by POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL, not by REST_SERVICE_URL as one might assume.
The default value is http://localhost:{port}. In a multi-container setup, localhost Inside the verifier container resolves to the verifier itself, not the issuer. The verifier cannot reach the issuer's status list, and verification fails with ResourceNotFound.
Setting POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL to the issuer's host bridge IP (http://172.20.0.1:8085 in our setup) Fixes this. The source of truth is line 48 of the bundled application.conf in the Cloud Agent JAR:
publicEndpointUrl = ${?POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL}Finding 4: The Vault file backend hits Linux path limits
Vault's file storage backend maps secret paths directly to filesystem paths. The Cloud Agent stores DIDComm keys using very long names, which exceed the Linux maximum path length when combined with Vault's nested directory structure. The result is an error:
open /vault/data/logical/.../metadata/[very long key]: file name too longThe fix is to use Vault's Raft-integrated storage backend instead. Raft uses BoltDB, which stores all data in a single database file and has no path length constraints. This is confirmed in the Vault GitHub issue tracker (issue #6210, filed February 2019, still open and reproducible with the file backend).
Finding 5: Cloud Agent requires Vault KV v2, not KV v1
Vault Raft initializes with no secrets engine mounted. The Cloud Agent v2.2.0 requires KV version 2 at the secret/ path. If KV v1 is mounted (which is what vault secrets enable -path=secret kv creates), the agent will fail with a 404 when trying to write wallet seeds.
The path structure differs: KV v2 uses secret/data/{key} while KV v1 uses secret/{key}. The agent always targets the v2 path.
Enable KV v2 explicitly: vault secrets enable -path=secret kv-v2.
Finding 6: Vault startup ordering matters
The Cloud Agent initializes its default wallet during startup. If Vault is not yet unsealed when the agent starts, the wallet initialization fails, and the agent crashes. On subsequent restarts, it finds the wallet record in Postgres but cannot find the corresponding seed in Vault, producing the error Wallet seed for wallet 00000000... does not exist.
The solution is to add a healthcheck to the Vault container and set the Cloud Agent's depends_on condition to service_healthy rather than service_started. The healthcheck polls vault status and waits for Sealed: false before Docker considers Vault ready.
Finding 7: The full Cardano infrastructure is heavy
Running a complete Cardano Preprod stack, node, wallet, and db-sync, requires significant resources:
Component | Approximate RAM |
|---|---|
cardano-node | 5GB |
cardano-db-sync | 2-3GB |
issuer prism-node | 2.5GB |
verifier prism-node | 1.5GB |
Cloud Agents (x3) | 600MB each |
A machine with 15GB RAM assigned to Docker is at the practical minimum for running issuer and verifier simultaneously alongside the Cardano stack. db-sync can be stopped once the prism-nodes have synced past the required block.
For small teams or individual developers, this is a meaningful infrastructure burden. The verifier's prism-node must sync the entire Cardano preprod chain history to resolve a DID published recently, which takes 2-3 hours on the first run. There is currently no lightweight path to DID resolution without running a full node stack.
This is a real constraint for new teams building on Identus. A future bridge between the Identus prism-node API contract and a Blockfrost-style API could eliminate this requirement for verification-only use cases, but no such bridge exists at the time of writing.
Why This Matters for Zivana
The tailor in Oshodi does not need to understand how DID resolution works. She does not need to know what Cardano is. But she needs the system built for her to actually work, to be trustworthy, to be portable, to not depend on any single company staying online or staying honest.
VAL-003 proves that the identity layer underneath Zivana Protocol is real. A credential issued by one agent can be independently verified by a completely separate agent, using only a public blockchain as the reference point. No central server. No API call to the issuer. No trust in any single party.
This is what self-sovereign identity means in practice. And for the informal economy, where institutions are often inaccessible or untrustworthy, this is not a feature. It is the foundation.
The findings documented here are also a contribution to the ecosystem. Every team building on Hyperledger Identus will encounter at least several of these issues. We are publishing them because good infrastructure documentation is itself a public good.
What Comes Next
VAL-003 is one of six validation exercises in Zivana Protocol's Phase 0. Each one proves that a specific component of the stack works on real infrastructure before protocol logic is built on top.
The Phase 0 approach is deliberate. It is easy to build a demo that works on a laptop. It is harder to build infrastructure that works when the conditions are real: real blockchain, real fees, real network boundaries, real memory constraints, real failure modes. Phase 0 is where those real conditions are encountered and resolved.
The findings from each validation exercise will be published here. Follow the Zivana Protocol blog and the Zivana GitHub organization for updates as they are released.
All evidence cited in this post is verifiable on Cardano preprod. The repository is at github.com/zivana-labs/zivana-validation. The Hyperledger Identus Cloud Agent source referenced throughout is at github.com/hyperledger-identus/cloud-agent tag v2.2.0.
Check Our Other Validation Works