canton-middleware

module

v0.5.2 Latest Latest Go to latest Published: Jun 10, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

README ¶

Canton Middleware

MetaMask-compatible middleware for Canton Network, enabling ERC-20 style interactions with Splice-compliant CIP-56 tokens.

Overview

This project provides:

API Server -- Ethereum JSON-RPC facade that translates MetaMask transactions to Canton CIP-56 operations
Relayer -- Bridges PROMPT tokens between Ethereum and Canton
Interoperability -- Native Canton users (e.g. Canton Loop) and MetaMask users can seamlessly transfer tokens to each other
Splice Token Standard (CIP-0056) -- All tokens implement the Splice HoldingV1, TransferFactory, and Metadata interfaces
Splice Registry API -- External wallets discover TransferFactory contracts for explicit disclosure during transfers
External Parties -- All users are allocated as external parties using the Interactive Submission API (no ~200 internal party limit)

Quick Start (Local Development)

# 1. Bootstrap: starts Docker, registers users, mints tokens
./scripts/testing/bootstrap-local.sh --clean

# 2. Test: runs all 8 interop + bridge test steps
go run scripts/testing/interop-demo.go

Both scripts auto-detect all dynamic configuration (domain IDs, party IDs, contract addresses) from the running Docker containers. See the Local Interop Testing Guide for full details.

Prerequisites

Tool	Version	Install
Go	1.23+	https://go.dev/dl/
Docker	Latest	https://docs.docker.com/get-docker/
Docker Compose	v2+	(included with Docker Desktop)
Foundry	Latest	`curl -L https://foundry.paradigm.xyz \| bash && foundryup`

MetaMask Configuration

After bootstrap completes, configure MetaMask:

Setting	Value
Network Name	Canton Local
RPC URL	`http://localhost:8081/eth`
Chain ID	31337
Currency Symbol	ETH

Test Accounts (Anvil defaults):

User	Address	Private Key
User 1	`0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`	`ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`
User 2	`0x70997970C51812dc3A010C7d01b50e0d17dc79C8`	`59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d`

Token Addresses:

Token	Address	Type
DEMO	`0xDE30000000000000000000000000000000000001`	Native Canton token
PROMPT	`0x5FbDB2315678afecb367f032d93F642f64180aa3`	Bridged ERC-20

Service Endpoints

Service	URL
API Server (MetaMask RPC)	http://localhost:8081/eth
User Registration	http://localhost:8081/register
Splice Registry API	http://localhost:8081/registry/transfer-instruction/v1/transfer-factory
API Server Health	http://localhost:8081/health
Canton gRPC	localhost:5011
Canton HTTP	http://localhost:5013
Anvil (Ethereum)	http://localhost:8545
PostgreSQL	localhost:5432
Relayer Metrics	http://localhost:9090/metrics
Prometheus UI	http://localhost:9091
Grafana UI	http://localhost:3001

Monitoring

docker compose up brings up Prometheus and Grafana alongside the application services.

Prometheus scrapes the relayer's /metrics endpoint on relayer:9090 every 15 s. The Prometheus UI is available at http://localhost:9091.
Grafana is pre-provisioned with Prometheus as the default data source (no manual setup required). Open http://localhost:3001 — login with admin / admin.

Configuration files:

File	Purpose
`deployments/prometheus/prometheus.yml`	Prometheus scrape config
`deployments/grafana/provisioning/datasources/prometheus.yaml`	Grafana auto-provisioned Prometheus datasource

Architecture

┌─────────────────┐                    ┌─────────────────┐
│    MetaMask     │                    │  Canton Loop /  │
│   (EVM Wallet)  │                    │  Native Canton  │
└────────┬────────┘                    └────────┬────────┘
         │ JSON-RPC                             │ gRPC / Registry API
         ▼                                      ▼
┌──────────────────────────────────────────────────────────┐
│                     API SERVER                            │
│  • /eth         - JSON-RPC facade (MetaMask-compatible)   │
│  • /register    - User registration (EVM + Canton native) │
│  • /registry/…  - Splice Registry API (TransferFactory)   │
│  • Custodial Canton key management (AES-256-GCM)          │
│  • Balance reconciliation with Canton                     │
└────────────────────────┬─────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  PostgreSQL │   │   Canton    │   │   Relayer   │
│  (Users/    │   │  (CIP-56    │   │  (ERC-20    │
│   Balances) │   │   Ledger)   │   │   Bridge)   │
└─────────────┘   └─────────────┘   └──────┬──────┘
                                           │
                                    ┌──────▼──────┐
                                    │  Ethereum   │
                                    │  (Anvil /   │
                                    │   Mainnet)  │
                                    └─────────────┘

How Transfers Work

All users are external parties on Canton. They hold their own signing keys and use the Interactive Submission API (prepare/sign/execute) instead of the standard CommandService.

MetaMask / cast send / Canton Loop
        │
        ▼
  /eth endpoint (JSON-RPC)  or  Interactive Submission (gRPC)
        │
        ▼
  Resolve Canton signing key from encrypted DB store
        │
        ▼
  PrepareSubmission → sign with user's key → ExecuteSubmission
        │
        ▼
  Canton Ledger: TransferFactory_Transfer (Splice-compliant CIP-56)

Tokens

Token	Type	Description
DEMO	Native Canton (CIP-56)	Minted directly on Canton via `CIP56Manager`, implements Splice `HoldingV1`
PROMPT	Bridged ERC-20	Bridged from Ethereum via the Wayfinder bridge, also uses Splice `HoldingV1`

Both tokens carry Splice-standard metadata (TextMap Text) with DNS-prefixed keys (e.g. splice.chainsafe.io/symbol). Metadata is propagated through all transfers via the TransferFactory.

Project Structure

canton-middleware/
├── cmd/
│   ├── api-server/              # API server entry point
│   └── relayer/                 # Relayer entry point
├── pkg/
│   ├── apidb/                   # API database operations (users, balances, whitelist)
│   ├── app/                     # Application wiring (api server, http server)
│   ├── auth/                    # JWT and EVM authentication
│   ├── cantonsdk/               # Canton SDK
│   │   ├── bridge/              #   ERC-20 ↔ Canton bridge operations
│   │   ├── client/              #   High-level SDK facade
│   │   ├── identity/            #   Party allocation, fingerprint mappings
│   │   ├── lapi/v2/             #   Generated Ledger API v2 protobufs
│   │   ├── ledger/              #   Low-level gRPC client (state, commands, auth)
│   │   ├── token/               #   CIP-56 token operations (mint, burn, transfer)
│   │   └── values/              #   Daml value encoding/decoding helpers
│   ├── config/                  # Configuration loading
│   ├── db/                      # Relayer database schema
│   ├── ethereum/                # Ethereum client and ABI
│   ├── ethrpc/                  # Ethereum JSON-RPC server
│   ├── keys/                    # Custodial key management (secp256k1, AES-256-GCM)
│   ├── registration/            # User registration handler
│   ├── registry/                # Splice Registry API handler
│   ├── relayer/                 # Bridge relayer logic
│   └── service/                 # Token service layer
├── contracts/
│   ├── canton-erc20/            # DAML contracts (CIP-56, Splice-compliant)
│   └── ethereum-wayfinder/      # Solidity bridge contracts
├── scripts/
│   ├── setup/                   # Bootstrap and infrastructure scripts
│   ├── testing/                 # Test and demo scripts
│   ├── bridge/                  # Bridge operation scripts
│   ├── demo/                    # Demo scripts
│   ├── remote/                  # Remote deployment scripts
│   ├── utils/                   # Diagnostic utilities
│   ├── lib/                     # Shared bash functions
│   └── archive/                 # Archived migration scripts
├── docs/                        # Documentation
├── deployments/                 # Docker, Canton, Prometheus configs
└── proto/                       # Protobuf definitions

Scripts

Testing (`scripts/testing/`)

Script	Description
`bootstrap-local.sh`	Full local bootstrap (Docker, users, tokens)
`interop-demo.go`	8-step interop + bridge test suite
`demo-activity.go`	Display Canton token activity (holdings, configs, events)
`canton-transfer-demo.go`	Demo transfers and reconciliation
`register-native-user.go`	Register a native Canton user
`register-user.go`	Register an EVM user
`e2e-local.go`	End-to-end local tests
`test-reconcile.go`	Test balance reconciliation
`test-whitelist.go`	Test whitelist functionality

Setup (`scripts/setup/`)

Script	Description
`bootstrap-all.sh`	Full automated setup (alternative to bootstrap-local.sh)
`bootstrap-bridge.go`	Bootstrap bridge contracts on Canton
`bootstrap-demo.go`	Mint DEMO tokens to users
`docker-bootstrap.sh`	Docker-specific bootstrap
`setup-local.sh`	Local environment setup
`setup-devnet.sh`	DevNet setup
`build-dars.sh`	Build DAML archives
`generate-protos.sh`	Regenerate protobuf Go code

Bridge (`scripts/bridge/`)

Script	Description
`bridge-activity.go`	Display recent bridge activity
`bridge-deposit.go`	Deposit ERC-20 to Canton
`get-holding-cid.go`	Get holding contract ID for withdrawals
`initiate-withdrawal.go`	Initiate Canton → Ethereum withdrawal
`cleanup-withdrawals.go`	Clean up processed withdrawals

Utilities (`scripts/utils/`)

Script	Description
`check-user-holdings.go`	Check user holdings on Canton
`verify-canton-holdings.go`	Verify/compare holdings (DB vs Canton)
`list-parties.go`	List known parties
`list-users.go`	List registered users
`check-mappings.go`	Check fingerprint mappings
`reconcile.go`	Manual balance reconciliation
`reset-demo-state.go`	Reset demo state
`query-canton-holdings.sh`	Query Canton holdings (bash)
`metamask-info.sh`	Show MetaMask config
`mock-oauth2-server.go`	Local OAuth2 mock server

Development

Build

go mod download
go build ./...

Lint

golangci-lint run ./...

Manual Setup

export CANTON_MASTER_KEY=$(openssl rand -base64 32)
export SKIP_CANTON_SIG_VERIFY=true

docker compose up -d

# Wait for healthy status, then bootstrap
go run scripts/setup/bootstrap-bridge.go -config config.e2e-local.yaml
go run scripts/setup/bootstrap-demo.go -config config.e2e-local.yaml

Verify Setup

curl http://localhost:8081/health
curl -X POST http://localhost:8081/registry/transfer-instruction/v1/transfer-factory
go run scripts/utils/check-user-holdings.go -config config.e2e-local.yaml

Configuration

Environment	Config File
Local testing	`config.e2e-local.yaml`
Docker	`config.docker.yaml`
API server (Docker)	`config.api-server.docker.yaml`
Local devnet	`config.local-devnet.yaml`
Example	`config.example.yaml`

Key Canton-specific fields (auto-detected by bootstrap):

Field	Description
`domain_id`	Canton synchronizer domain ID
`relayer_party`	Bridge relayer / token issuer party
`instrument_admin`	Party administering token instruments
`instrument_id`	Token instrument identifier (e.g. `PROMPT`)
`cip56_package_id`	`cip56-token` DAR package hash
`splice_holding_package_id`	Splice `HoldingV1` interface DAR hash
`splice_transfer_package_id`	Splice `TransferFactory` interface DAR hash
`bridge_package_id`	`bridge-wayfinder` DAR package hash

Documentation

Document	Description
dApp & Snap Testing	Testing with the Wayfinder dApp and MetaMask Snap
Local Interop Testing	Full local bootstrap and 8-step interop test guide
API Documentation	Endpoint reference (JSON-RPC, Registration, Splice Registry)
Architecture	System design and data flows
DevNet Interop Testing	DEMO token testing on ChainSafe DevNet
CIP-0086 Overview	CIP-0086 compliance
Deployment Requirements	Production deployment checklist

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for the full license text and NOTICE for attributions of third-party software included in or depended on by this project.

Directories ¶

Path	Synopsis
cmd
api-server command
api-server/migrate command
generate-test-vectors command Command generate-test-vectors produces deterministic crypto test vectors for cross-validation with the canton-snap TypeScript implementation.	Command generate-test-vectors produces deterministic crypto test vectors for cross-validation with the canton-snap TypeScript implementation.
indexer command
indexer/migrate command
relayer command
relayer/migrate command
internal
metrics Package metrics provides shared helpers and presets for Prometheus instrumentation.	Package metrics provides shared helpers and presets for Prometheus instrumentation.
pkg
app Package app defines common runtime contracts shared by different executable entrypoints (e.g., API server, relayer, migration runner).	Package app defines common runtime contracts shared by different executable entrypoints (e.g., API server, relayer, migration runner).
app/api Package api implements app.Runner for the API server process.	Package api implements app.Runner for the API server process.
app/errors Package errors contains helper functions and types to work with errors	Package errors contains helper functions and types to work with errors
app/http Package http provides HTTP utilities including chi-compatible error handling	Package http provides HTTP utilities including chi-compatible error handling
app/indexer Package indexer implements the runner for the indexer process.	Package indexer implements the runner for the indexer process.
app/relayer Package relayer implements app.Runner for the relayer process.	Package relayer implements app.Runner for the relayer process.
auth
cantonsdk/bridge Package bridge implements optional Wayfinder bridge operations for Canton.	Package bridge implements optional Wayfinder bridge operations for Canton.
cantonsdk/client Package client provides the high-level Canton SDK client.	Package client provides the high-level Canton SDK client.
cantonsdk/identity Package identity implements Canton identity operations such as party management and fingerprint-to-party mapping.	Package identity implements Canton identity operations such as party management and fingerprint-to-party mapping.
cantonsdk/lapi/v2
cantonsdk/lapi/v2/admin
cantonsdk/lapi/v2/interactive
cantonsdk/lapi/v2/interactive/transaction/v1
cantonsdk/ledger Package ledger implements the low-level Canton Ledger API client.	Package ledger implements the low-level Canton Ledger API client.
cantonsdk/streaming Package streaming provides a reusable, generic Canton ledger streaming client.	Package streaming provides a reusable, generic Canton ledger streaming client.
cantonsdk/token Package token implements CIP-56 token operations such as mint, burn, transfer, and balance queries.	Package token implements CIP-56 token operations such as mint, burn, transfer, and balance queries.
cantonsdk/values Package values provides helper utilities for working with Canton Ledger API value types.	Package values provides helper utilities for working with Canton Ledger API value types.
config
custodial Package custodial implements background automation for custodial Canton parties.	Package custodial implements background automation for custodial Canton parties.
custodial/mocks
ethereum
ethereum/contracts
ethrpc
ethrpc/miner
ethrpc/miner/mocks
ethrpc/service
ethrpc/service/mocks
ethrpc/store
ethrpc/submitter Package submitter drains pending mempool entries by submitting the corresponding ERC-20 transfer to Canton.	Package submitter drains pending mempool entries by submitting the corresponding ERC-20 transfer to Canton.
ethrpc/submitter/mocks
indexer
indexer/client Package client provides an HTTP client for the indexer's admin API.	Package client provides an HTTP client for the indexer's admin API.
indexer/client/mocks
indexer/engine
indexer/engine/mocks
indexer/service
indexer/service/mocks
indexer/store
keys Package keys provides Canton key generation and encryption for custodial key management.	Package keys provides Canton key generation and encryption for custodial key management.
log
migrations/apidb Package apidb holds all the migrations for the API database	Package apidb holds all the migrations for the API database
migrations/indexerdb Package indexerdb holds all migrations for the indexer database.	Package indexerdb holds all migrations for the indexer database.
migrations/relayerdb Package relayerdb holds all the migrations for the relayer database	Package relayerdb holds all the migrations for the relayer database
pgutil
pgutil/migrations Package migrations holds migrations related helpers	Package migrations holds migrations related helpers
reconciler
reconciler/store
registry Package registry implements the Splice Registry API for external wallet integration.	Package registry implements the Splice Registry API for external wallet integration.
relayer
relayer/engine
relayer/engine/mocks
relayer/service Package service provides the relayer HTTP service layer.	Package service provides the relayer HTTP service layer.
relayer/service/mocks
relayer/store
token
token/mocks
token/provider
transfer Package transfer implements the non-custodial prepare/execute transfer API.	Package transfer implements the non-custodial prepare/execute transfer API.
transfer/mocks
user
user/service
user/service/mocks
userstore
scripts Package tools pins script dependencies so go mod tidy does not remove them.	Package tools pins script dependencies so go mod tidy does not remove them.
utils/dockerconfig Package dockerconfig loads the api-server config from a running Docker stack.	Package dockerconfig loads the api-server config from a running Docker stack.
tests
e2e/cmd/devstack command devstack manages the Docker Compose devstack lifecycle for E2E tests.	devstack manages the Docker Compose devstack lifecycle for E2E tests.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL