This repository builds upon the excellent acapy demo project to provide a comprehensive practice environment for exploring agent-controller relationships in ACA-Py. Designed to support team learning and client education, this resource is particularly valuable for beginners working with ACA-Py multitenancy.
To begin, you will need access to an Indy blockchain network and an endorser DID with transaction authority. This guide uses the testnet operated by the ACA-Py team.
Please register an endorser DID with a seed at https://test.bcovrin.vonx.io and securely store the seed for later use.
Environment variables defined in the .env file are automatically loaded into each container when Docker Compose starts.
- Copy the environment template to create your configuration file:
cp env.template .env- Edit the .env file with your preferred editor:
vi .envConfigure the following required variables:
ISSUER_PUBLIC_DID_SEED: The seed for the endorser DID you registered aboveSCHEMA_VERSION: A semantic version string (e.g., '1.0.0') that has not been registered on the ledger yet
docker compose builddocker compose up -dAllow a few moments for all containers to start up, then execute the setup script:
docker compose exec setup python3 setup.pydocker compose down
docker compose up -dYour environment is now ready for use.
The following services are available on these ports:
- 8000: ACA-Py Agent
- 8001: ACA-Py Admin API
- 8002: Holder Agent Controller
- 8003: Issuer Agent Controller
- 8004: Verifier Agent Controller
curl http://localhost:8003/schemas
curl http://localhost:8003/credential-definitions
curl http://localhost:8003/revocation/registriesThis example demonstrates credential issuance using an out-of-band invitation with an attached credential offer.
In a typical scenario, the holder would receive an out-of-band invitation through other means, such as scanning a QR code generated by the issuer. This example provides a simplified demonstration of the issuance flow for learning purposes.
The following API call will receive and accept an out-of-band invitation from the issuer. The invitation includes an attached credential offer, and during processing, the holder automatically receives the credential. This is a connection-less exchange, so no persistent connection is established.
curl http://localhost:8002/issue-credential/transcriptFrom the holder's perspective, this connection-less exchange results in a new credential and credential exchange record, but no persistent connection.
curl http://localhost:8002/credentials
curl http://localhost:8002/issue-credential/records
curl http://localhost:8002/connectionsFrom the issuer's perspective, a credential exchange record is created without establishing a connection, as the out-of-band invitation was created without handshake protocols.
curl http://localhost:8003/issue-credential/records
curl http://localhost:8003/connectionsThis example demonstrates proof presentation using a connection-less approach.
The following API call will receive and accept an out-of-band invitation from the verifier. The invitation contains an attached presentation request. The holder will construct a proof based on this request and submit it to the verifier.
curl http://localhost:8002/present-proof/transcriptFrom the holder's perspective, this connection-less exchange results in a new proof exchange record, but no persistent connection.
curl http://localhost:8002/present-proof/records
curl http://localhost:8002/connectionsThe verifier maintains no persistent connection due to the connection-less nature of this proof presentation, but does receive a present-proof record.
curl http://localhost:8004/present-proof/records
curl http://localhost:8004/connectionsThe following API calls will remove all the data generated by the operations above.
curl http://localhost:8002/cleanup
curl http://localhost:8003/cleanup
curl http://localhost:8004/cleanup