Start Here¶

Hyperledger Cacti is a pluggable interoperability framework for distributed ledger and blockchain networks. This page helps you find the right documentation based on what you want to do with Cacti.

Choose Your Path¶

Cacti serves three distinct audiences. Identify your role below and follow the corresponding section to get started.

Role	Description	Section
Contributor	You want to modify, extend, or fix the Cacti codebase itself.	For Contributors
Developer	You want to use Cacti packages as dependencies in your own application.	For Developers
Operator	You want to deploy and run Cacti components	For Operators

The following diagram illustrates how each role interacts with the Cacti ecosystem:

flowchart LR
    B{"Goal"}
    B -->|"Modify the<br/>Cacti codebase"| C["Contributor"]
    B -->|"Use Cacti as<br/>a dependency"| D["Developer"]
    B -->|"Deploy and<br/>run Cacti"| E["Operator"]

    C --> C1["BUILD.md"]
    C --> C2["CONTRIBUTING.md"]
    C --> C3["CONVENTIONS.md"]

    D --> D1["Ledger Connectors"]
    D --> D2["API Server"]
    D --> D3["Cross-Chain Protocols"]

    E --> E1["Deployment Patterns"]
    E --> E2["Runtime Configuration"]
    E --> E3["Monitoring"]

For Contributors¶

This section is for anyone who wants to build, modify, or contribute code and documentation to the Cacti repository.

Prerequisites¶

Before you begin, ensure you have the following installed:

Installation¶

The fastest way to set up a working development environment is with the Nix flake. This provisions the full polyglot toolchain (Node.js, Go, Rust, JDK, Protobuf, Foundry) in a single command. See the Nix Setup Guide.

# 1. Clone the repository
git clone https://github.com/hyperledger-cacti/cacti.git
cd cacti

# 2. Enter the Nix development shell
nix develop

# 3. Install dependencies and build
yarn run configure

Alternative setup methods are available if Nix is not suitable for your environment. The different setup methods are:

Method	Description	Guide
Nix Flake	One-command reproducible toolchain setup (recommended)	BUILD.md - Nix Flake Quickstart
Dev Container	Docker-based VS Code development environment	BUILD.md - Dev Container Quickstart
Manual Setup	Platform-specific installation (macOS, Linux, Windows/WSL)	BUILD.md - Getting Started

For Developers¶

This section is for anyone who want to use Cacti packages as dependencies in their own applications. You do not need to clone or build the Cacti repository; instead, you can leverage the project artifacts (npm packages, docker images), or compile them from source.

What Cacti Provides¶

Cacti is a modular framework. You can adopt as much or as little of it as your project requires. The following table lists the primary component categories:

Component	Description	Package Scope
Ledger Connectors	Plugins that abstract interaction with specific blockchains (Besu, Fabric, Ethereum, Corda, Stellar)	`@hyperledger/cactus-plugin-ledger-connector-*`
API Server	Express-based server that hosts plugins and exposes REST/gRPC APIs	`@hyperledger/cactus-cmd-api-server`
Core Libraries	Common interfaces, types, utilities, and plugin registry	`@hyperledger/cactus-core`, `cactus-core-api`, `cactus-common`
Cross-Chain Protocols	SATP Hermes (asset transfer), Weaver (relay-based interop), COPM (cross-chain operations)	`@hyperledger/cactus-plugin-satp-hermes`, etc.
Keychain Plugins	Secure credential storage (Vault, AWS SM, Azure KV, in-memory)	`@hyperledger/cactus-plugin-keychain-*`
Test Tooling	Docker-based test ledgers and utilities for integration testing	`@hyperledger/cactus-test-tooling`

Choosing Your Level of Integration¶

Cacti supports three levels of integration depth. Choose the level that matches your project requirements:

Level	Use Case	Complexity	What You Get
Level 1: Connector as a Library	You have an existing Node.js application and need blockchain connectivity	Low	Connector as an npm dependency with direct programmatic access
Level 2: API Server with Plugins	You have a non-Node.js application or want containerized blockchain access	Medium	Standalone API server exposing REST/gRPC endpoints
Level 3: Full Framework Integration	You want a complete blockchain-integrated application framework	High	Full stack with custom business logic plugins

Level 1: Connector as a Library¶

Install a connector directly into your existing Node.js or TypeScript project:

npm install @hyperledger/cactus-plugin-ledger-connector-ethereum
npm install @hyperledger/cactus-core
npm install @hyperledger/cactus-common

This gives you type-safe, programmatic access to blockchain operations without additional infrastructure.

Level 2: API Server with Plugins¶

Run the Cacti API server as a standalone service and interact with it over REST or gRPC from any language:

npm install @hyperledger/cactus-cmd-api-server

Configure plugins via a JSON configuration file and access blockchain operations through the server's HTTP endpoints.

Level 3: Full Framework Integration¶

Build custom business logic plugins that run inside the Cacti API server. This is the deepest level of integration and is suited for projects that want to leverage the full plugin architecture.

Developer Resources¶

Resource	Description
Getting Started Guide	Detailed tutorials for each integration level with code examples
Architecture Overview	System design and component relationships
OpenAPI Specifications	Auto-generated API reference for all plugin endpoints
Weaver Documentation	Relay-based interoperability framework
SATP Hermes	Secure Asset Transfer Protocol implementation

For Operators¶

This section is for anyone responsible for deploying, configuring, and running Cacti components in production or staging environments.

Deployment Overview¶

Cacti components are designed to run as containerized services. A typical production deployment involves the following:

Component	Role	Runtime
API Server	Hosts ledger connector plugins and exposes REST/gRPC APIs	Node.js process or Docker container
Ledger Connector Plugins	Communicate with blockchain nodes (Besu, Fabric, etc.)	Loaded into the API server at startup
Relays (Weaver)	Route cross-network verification requests between organizations	Standalone service (Rust or Node.js)
Drivers (Weaver)	Interface between relays and specific ledger networks	Standalone service per ledger type

Deployment Patterns¶

Cacti supports multiple deployment patterns depending on your infrastructure and security requirements:

Pattern	Description	When to Use
Single-Organization	One API server instance with connectors for each ledger	Development, testing, and single-organization use cases
Multi-Organization with Relays	Weaver relays and drivers deployed per organization	Cross-organization interoperability requiring independent governance
Hybrid	API server for direct ledger access combined with relays for cross-network operations	Complex deployments spanning multiple interoperability modes

Runtime Configuration¶

The API server is configured through a JSON configuration file that specifies which plugins to load and how to connect to ledger nodes. Key configuration areas include:

Plugin Registration: Which ledger connectors and keychain plugins to activate at startup.
Network Endpoints: RPC URLs, TLS certificates, and authentication credentials for each blockchain node.
CORS and Security: Allowed origins, API keys, and authorization policies.
Logging: Log levels and output destinations for operational monitoring.

See BUILD.md - Configure Cacti for detailed configuration instructions and examples.

Weaver Deployment¶

For relay-based cross-network interoperability, the Weaver subsystem requires additional components:

Relay Server: Routes verification requests between networks. See Weaver Relay Architecture for design details.
Drivers: Network-specific adapters that translate relay requests into ledger queries. Drivers exist for Fabric, Corda, and Besu.
Interoperation Modules: Smart contracts or chaincode installed on each participating network to handle verification logic.

For detailed deployment instructions, refer to the Weaver Getting Started Guide.

Monitoring and Health Checks¶

The API server exposes health check endpoints that can be integrated with container orchestrators (Kubernetes, Docker Compose) for liveness and readiness probes. Configure your orchestrator to poll the health endpoint at the API server's base URL.

Operator Resources¶

Resource	Description
BUILD.md - Configure Cacti	Server configuration, plugin registration, and CORS setup
Weaver Getting Started	End-to-end setup for cross-network interoperability

For Contributors¶

Making Your First Contribution¶

Once your environment is set up, follow this workflow to submit your first pull request:

Fork the repository on GitHub.
Create a branch from main with a descriptive name.
Make your changes in small, focused commits.

Run the local CI checks before pushing:

yarn run configure
yarn run lint
yarn run test:jest:all

Push and open a pull request against upstream/main.

Contributor Documentation¶

The following documents govern the contribution process, coding standards, and review expectations:

Document	Purpose
BUILD.md	Development environment setup and build instructions
CONTRIBUTING.md	Contribution workflow, PR process, and review guidelines
CONVENTIONS.md	Coding standards, package structure, and repository conventions
PULL.md	Pull request quality standards and review criteria
AI_GUIDELINES.md	Guidelines for AI-assisted contributions

Additional Resources¶

Resource	Description
ROADMAP.md	Project roadmap and planned integrations
Hyperledger Cacti Documentation	Full documentation site
Discord	Community chat and support
Mailing List	Project mailing list