didx-cloud

🚧 This project is currently under development. If you would like to use this in production, please contact us first to discuss your use case.

Overview

This project comprises a FastAPI application built around ACA-Py, primarily tailored for Yoma-specific use cases.

The main app provides an API interface that simplifies complex self-sovereign identity (SSI) workflows. Using our ACA-Py controller, it provides a streamlined layer of abstraction for client applications (e.g., a mobile app) to interact within an SSI ecosystem.

What would normally require multiple calls to ACA-Py can be condensed into a single call through this API. For example, onboarding an issuer — which involves creating a wallet, establishing a connection with an endorser, generating a public DID, accepting the Transaction Author Agreement (TAA), publishing the DID to the ledger, and awaiting confirmation — can all be achieved with a single API call. Convenient, isn't it?

We simplify several key capabilities, including:

• Creating and managing wallets
• Onboarding issuers and verifiers
• Managing connections between parties
• Creating schemas and credential definitions
• Issuing verifiable credentials and handling revocations
• Requesting and validating proofs

To enable this, the project includes essential supporting services:

• An Endorser agent and service for authorizing ledger transactions
• A Trust Registry implementation for authorizing valid issuers, verifiers, and approved credential schemas
• A webhooks service (Waypoint) for real-time, server-sent event (SSE) notifications and updates

You can find more detailed documentation in the docs folder. The Quick Start, Common Steps and Example Flows will be most useful.

How to Run It

Note

For local development we now use Tilt and Kind instead of Docker Compose. Legacy Docker Compose files are still available, but deprecated and will be removed in the future.

Running the project is straightforward — it's all containerized. Simply execute mise run tilt:up from the project root. This command will spin up a Kind cluster, build all the necessary docker images, and start the project. You can then visit localhost:10350 to access the Tilt UI.

Requirements

To run the project, you will need Docker and docker-compose, as well as the ability to run a POSIX shell (e.g., sh or bash).

To install Docker, follow the instructions for your operating system in the official docs.

Next, follow the instructions for docker-compose in their docs.

If you experience any issues while running the project, feel free to reach out by opening an issue or contacting one of the contributors.

Setting up Mise

This project makes use of Mise to install and manage dev tooling.

There are several options for installing Mise:

# Homebrew
brew install mise

# Build from source (if you have Rust installed)
cargo install mise

# Arch Linux User Repository
yay -S mise-bin

# Debian/Ubuntu APT (amd64)
sudo apt-get update -y && sudo apt-get install -y gpg wget curl
sudo install -dm 755 /etc/apt/keyrings
wget -qO - https://mise.jdx.dev/gpg-key.pub \
  | gpg --dearmor \
  | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=amd64] https://mise.jdx.dev/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/mise.list
sudo apt-get update
sudo apt-get install -y mise

# Debian/Ubuntu APT (arm64)
sudo apt-get update -y && sudo apt-get install -y gpg wget curl
sudo install -dm 755 /etc/apt/keyrings
wget -qO - https://mise.jdx.dev/gpg-key.pub \
  | gpg --dearmor \
  | sudo tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/mise.list
sudo apt-get update
sudo apt-get install -y mise

We strongly recommend using your system package manager to install Mise.

Additional installation documentation can be found here

Once you have Mise installed, you will need to activate it in your shell.

# Bash
echo 'eval "$(mise activate bash)"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc && source ~/.zshrc

# Fish
echo 'mise activate fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish

Once Mise is installed and activated, you can run mise trust and then mise install to install all the required tools.

Other shells are supported as well. Please refer to the Mise documentation for more information.

Note

At the time of writing, Mise does not support Windows. WSL is recommended for Windows users.

If you are using WSL, you will need to take some additional steps for Kind to work.

Running Tests

The tests use pytest. For convenience, use Mise to run them. First, ensure the project is running locally by executing mise run tilt:up. In another shell, you can now run mise run tests to run all tests or mise run tests:unit to run only the unit tests.

mise run tilt:up

Install the requirements:

mise run poetry:install

To run the tests you need to set up some environment variables to point Pytest at the correct endpoints.

cp .env.example .env
source .env

Then you can run the tests:

poetry run pytest .

Or only the unit tests:

poetry run pytest --ignore=app/tests/e2e

You can specify the log level of the pytest output by using the --log-cli-level flag.

poetry run pytest . --log-cli-level=DEBUG

This will output all log messages with a log level of DEBUG or higher.

To run specific tests, you can specify the path to the test file and the test method. For example:

poetry run pytest \
  app/tests/e2e/test_verifier_oob.py::test_accept_proof_request_oob \
  --log-cli-level=1

Running containerised tests

mise run tilt:up

In another terminal:

helmfile apply \
  --environment local \
  -f ./tilt/.charts/helmfiles/aries-capi-test.yaml

CI/CD

Please, refer to the CI/CD docs for more information.

Contributing

While this project was primarily developed to meet the needs of Yoma, it is an open-source project that can be used for other Hyperledger Aries projects as well. We welcome contributions from everyone. Feel free to engage in discussions, create pull requests against existing tickets, or open new issues following the GitHub guidelines.