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.