CompliGate

Deterministic Compliance Authorization for XRPL Transactions

CompliGate is an XRPL-focused authorization and verification layer that defines the conditions under which a transaction is allowed to execute, links that authorization to a real XRPL testnet transaction, and produces a proof artifact for auditability.

CompliGate does not execute transactions as an intermediary. It generates authorization constraints and verifies settlement outcomes.

Current status: working XRPL testnet prototype with real transaction roundtrip, memo-linked bundle hashes, settlement verification, and proof artifacts. Compliance provider is currently mock_trm pending live provider access.

Executive Summary

CompliGate is an authorization and verification layer for tokenized-asset activity on XRPL. Given a proposed transaction, it evaluates configured policy and compliance evidence (KYC, sanctions screening, reserve / 1:1 backing) and issues a short-lived, Ed25519-signed Proof Bundle that encodes:

the decision (ALLOW / DENY),
the constraints under which the transaction may proceed (action, currency, issuer, amount ceiling, validity window),
a reference to the underlying compliance evidence, and
a bundle_hash suitable for embedding in an XRPL transaction memo.

After the user independently settles the transaction on XRPL, CompliGate verifies the on-ledger transaction against the constraints in the bundle and returns a deterministic settlement-verification result.

CompliGate does not custody assets, broker transactions, or submit settlement on behalf of users. It is a verifier, not an executor.

Why XRPL Needs This

XRPL is purpose-built for value movement. It provides fast, deterministic settlement and a mature issued-asset infrastructure — native trust lines, IOUs, and a built-in DEX — that make it a natural home for stablecoins and tokenized real-world assets. It also exposes issuer-side controls and transaction capabilities (e.g. issuer accounts, trust line authorization, freeze, RequireAuth, DisallowXRP, transfer fees, payment paths) that let an issuer shape who can hold an asset and how it can move.

What XRPL does not provide — and is not trying to provide — is the off-ledger compliance reasoning that regulated issuers and venues are now expected to perform on every transaction:

Is this counterparty subject to sanctions or KYC restrictions?
Is this asset properly classified (security, payment stablecoin, commodity-like token) for the jurisdictions involved?
For a payment stablecoin (e.g. RLUSD), is the 1:1 reserve backing currently attested?
Is the transaction within the jurisdiction, currency, issuer, and amount limits the institution authorized?
Can the institution later produce verifiable, tamper-evident proof that those checks were performed, and what they decided, for audit?

Regulated stablecoins and tokenized assets need deterministic compliance logic — the same inputs must always produce the same authorization decision, and that decision must be reconstructable after the fact. Emerging U.S. regulatory direction (SEC/CFTC tokenization guidance, the GENIUS Act for payment stablecoins, the CLARITY Act for market structure) is converging on the same expectations across jurisdictions: asset classification, 1:1 backing attestation, jurisdiction controls, and end-to-end auditability of every regulated transfer.

CompliGate complements XRPL by providing the authorization and proof layer around XRPL execution. It decides whether a proposed transaction is allowed under configured policy and compliance evidence before the user submits it, and after settlement it verifies the on-ledger transaction against that decision.

CompliGate does not change the XRPL protocol, does not require any amendment, and does not enforce policy on-ledger — XRPL still settles transactions exactly as it does today.

The enforcement boundary is the institution's submission path: only transactions accompanied by a valid, unexpired Proof Bundle are submitted, and the resulting on-ledger transaction is independently verifiable against the bundle via the embedded bundle_hash memo.

Problem → Solution

Problem	Solution
Compliance checks are handled off-chain and inconsistently	CompliGate generates deterministic authorization constraints
XRPL transactions do not automatically carry compliance context	CompliGate links `bundle_hash` to XRPL transaction memo
Settlement verification is difficult to audit	CompliGate fetches the XRPL `tx_hash` and produces a proof artifact
Sanctions/KYC/reserve providers may vary by institution	CompliGate uses a provider abstraction layer; current MVP uses `mock_trm`
Institutions need repeatable audit evidence	CompliGate stores permits, evidence context, and proof artifacts

Demo Flow

flowchart LR
    A[Treasury Decision] --> B[CompliGate Evaluation]
    B --> C[Signed Permit + Constraints]
    C --> D[XRPL Testnet Execution]
    D --> E[Settlement Verification]
    E --> F[Proof Artifact]

    B --> B1[Asset Classification]
    B --> B2[Sanctions Provider Abstraction]
    B --> B3[Jurisdiction + Limits]
    D --> D1[Memo: bundle_hash]
    F --> F1[tx_hash]
    F --> F2[ledger_index]
    F --> F3[reason_codes]

This is the current MVP demo path: Treasury Decision → CompliGate Evaluation → Permit → XRPL Execution → Proof.

End-to-end happy path (real XRPL testnet, mocked sanctions provider in MVP):

   ┌──────────┐    1. POST /v1/permit          ┌────────────────┐
   │  Client  │ ─────────────────────────────► │   CompliGate   │
   │ / dApp   │                                │    Backend     │
   └──────────┘                                └───────┬────────┘
        ▲                                              │
        │                                              │ evaluates KYC, sanctions,
        │                                              │ reserve, jurisdiction, limits
        │                                              ▼
        │  2. Proof Bundle (Ed25519-signed) + bundle_hash
        │ ◄────────────────────────────────────────────┘
        │
        │  3. Submit XRPL Payment with Memo = bundle_hash
        ▼
   ┌──────────────────────────────────────────────────────────┐
   │              XRP Ledger (Testnet)                        │
   │   Payment tx settles, returns tx_hash                    │
   └───────────────────────────┬──────────────────────────────┘
                               │
                               │  4. POST /v1/settle/verify { tx_hash, bundle, signature }
                               ▼
                    ┌────────────────────┐
                    │   CompliGate       │  fetches tx by hash, checks
                    │ verifies on-ledger │  amount / currency / issuer /
                    │ tx vs bundle       │  destination / memo == bundle_hash
                    └─────────┬──────────┘
                              │
                              ▼
                  5. Verification result + Proof artifact

Steps 3 and 4 use the real XRPL testnet via XRPL_RPC_URL. The sanctions check in step 1 is currently served by a mock provider unless an HTTP provider is configured (see Current Status & Limitations).

Visual Demo

Screenshots of the end-to-end flow will be added here before external review:

Treasury Decision / Permit Request — frontend permit form and signed Proof Bundle response.
XRPL Testnet Transaction — payment submission with bundle_hash memo.
Settlement Verification — POST /v1/settlement/verify result against the on-ledger transaction.
Proof Artifact — generated artifact referencing tx_hash and ledger_index.

Architecture

flowchart TB
    UI[React Frontend] --> API[FastAPI Backend]

    API --> Permit[Permit Service]
    API --> XRPL[XRPL Service]
    API --> Settlement[Settlement Verification Service]
    API --> Proof[Proof Artifact Service]

    Permit --> Policy[Policy Evaluation]
    Policy --> Provider[Compliance Provider Layer]
    Provider --> MockTRM[mock_trm Provider]
    Provider -. future .-> TRM[TRM Labs API]

    Permit --> DB[(PostgreSQL)]
    Proof --> DB
    Settlement --> DB

    XRPL --> Ledger[XRPL Testnet]
    Settlement --> Ledger

    Ledger --> Tx[tx_hash + memo bundle_hash]
    Settlement --> Artifact[Settlement Proof Artifact]

XRPL execution is real testnet
compliance provider is mock_trm in MVP
TRM integration is pending API access

Key properties:

CompliGate does not sit on the settlement path. Users submit their own XRPL transaction; CompliGate verifies it after the fact.
Providers are pluggable and fail-closed. The default kind is null, which denies. Configuration is explicit.
The Proof Bundle is the contract. It is canonical, signed, hashed, time-bound, and independently verifiable using only the public key from /public-key.

Current Capabilities

Current Status and Limitations

CompliGate is at MVP stage. This section is intentionally honest and technical about which pieces are real and which are stubs.

Current MVP includes:

Real XRPL testnet execution
Memo-linked authorization context
Settlement verification
PostgreSQL persistence
Proof artifacts

Current limitations:

Compliance provider is mock_trm, not live TRM
KYC and reserve/liquidity providers are not fully wired
Settlement verification still depends on persisted backend permit context
Replay/single-use enforcement is not fully hardened
Signer model is testnet/demo-oriented
Not production-ready for regulated environments

This repo should be evaluated as an XRPL-integrated compliance authorization prototype, not production financial infrastructure.

What CompliGate is explicitly not:

Not a broker, broker-dealer, custodian, or transaction intermediary.
Not an on-ledger enforcement mechanism — XRPL will execute a transaction whether or not CompliGate authorized it. CompliGate provides off-ledger authorization and on-ledger verification of conformance.
Not a substitute for a regulated KYC, sanctions, or proof-of-reserves provider. CompliGate consumes evidence from such providers; it does not produce it.

Quickstart

Prerequisites: Python 3.11+, Node 20+, and a reachable PostgreSQL instance.

PostgreSQL must be running and DATABASE_URL must be configured.

Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

Frontend

cd frontend
npm install
cp .env.example .env
npm run dev

Database

cd backend
alembic upgrade head

End-to-end XRPL testnet roundtrip (optional)

cd backend
python3 scripts/xrpl_testnet_roundtrip.py

Interactive API docs: http://localhost:8000/docs.

For deeper backend setup (Docker, production deployment, Alembic workflow, signing modes), see backend/README.md.

API Endpoints

All /v1/* endpoints are protected by API key authentication when keys are configured (X-API-Key header or Authorization: Bearer <key>). Public endpoints (/health, /public-key, /v1/xrpl/health) are intentionally unauthenticated so they can be used as liveness/discovery probes.

Method	Endpoint	Purpose	Auth Required
`GET`	`/health`	Liveness probe. Returns `{"status": "ok"}`.	No
`GET`	`/public-key`	Ed25519 public key (base64 + hex) used to verify Proof Bundle signatures.	No
`GET`	`/v1/xrpl/health`	Reports whether the configured XRPL network is reachable.	No
`POST`	`/v1/permit`	Run authorization. Returns a signed Proof Bundle with constraints, `iat`/`exp`, and `bundle_hash`.	Yes
`POST`	`/v1/verify`	Verify a Proof Bundle's signature and expiry without contacting XRPL.	Yes
`POST`	`/v1/xrpl/trustline/check`	Check whether an XRPL account has the RLUSD trust line (and capacity) required for settlement.	Yes
`POST`	`/v1/xrpl/payment`	Optional, gated XRPL signing/submission. Disabled unless `XRPL_SIGNING_ENABLED=true` and `XRPL_SIGNING_MODE=seed`. Testnet only.	Yes
`POST`	`/v1/settlement/verify`	Post-settlement verification of an XRPL `tx_hash` against a Proof Bundle's constraints.	Yes

Example — request a permit and verify it:

curl -X POST http://localhost:8000/v1/permit \
  -H "X-API-Key: local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{"subject": "rExampleSubjectAddress...", "action": "transfer", "amount": 100.00}'

curl -X POST http://localhost:8000/v1/settlement/verify \
  -H "X-API-Key: local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{"tx_hash": "<xrpl-tx-hash>", "bundle": { ... }, "signature": "<base64>"}'

Environment Variables

The table below covers the variables most commonly needed to run CompliGate. The full list — including every compliance-provider knob, signing mode, and persistence option — is documented in backend/.env.example, frontend/.env.example, and backend/README.md.

Variable	Purpose	Example
`DATABASE_URL`	PostgreSQL connection string used for permit / proof persistence. Required outside of narrow local experiments.	`postgresql+psycopg://compligate:password@localhost:5432/compligate`
`API_KEY_ENABLED`	Toggles API key authentication on the backend. Set to `false` only for local development.	`true`
`API_KEYS`	Comma-separated list of valid API keys accepted by the backend (secret — never commit this).	`never commit this`
`XRPL_RPC_URL`	XRPL JSON-RPC endpoint the backend talks to.	`https://s.altnet.rippletest.net:51234`
`XRPL_NETWORK`	Network identifier embedded in verification metadata.	`testnet`
`XRPL_SIGNING_ENABLED`	Master kill switch for XRPL signing. When `false`, the payment endpoint returns a structured error regardless of `XRPL_SIGNING_MODE`.	`true`
`XRPL_SIGNING_MODE`	Signing mode used by `/v1/xrpl/payment`: `seed` (dev/staging), `disabled`, or `external` (HSM placeholder, not implemented).	`seed`
`XRPL_SIGNER_SEED`	Seed used by the `seed` signing mode. Testnet only — never set to a mainnet seed (secret — never commit this).	`never commit this`
`XRPL_REQUIRE_TRUSTLINE`	Require an RLUSD trustline before settlement. Recommended `false` on testnet, `true` on mainnet.	`false`
`SANCTIONS_MODE`	Selects the sanctions provider implementation: `mock` (default, MVP simulation) or `live`.	`mock`
`FAIL_CLOSED_COMPLIANCE`	When `true` (default), `denied` or `unavailable` provider responses produce a `DENY`. Keep `true` outside of narrow local dev.	`true`
`TRM_SANCTIONS_API_KEY`	API key for the TRM sanctions provider used in `live` sanctions mode (secret — never commit this).	`never commit this`
`VITE_API_BASE`	Base URL of the CompliGate backend API used by the frontend.	`http://localhost:8000`
`VITE_API_KEY`	Build-time default API key sent by the frontend to the backend. Can be overridden at runtime in the UI (secret — never commit this).	`never commit this`
`VITE_XRPL_EXPLORER_BASE_URL`	Base URL of an XRPL transaction explorer used to deep-link `tx_hash` values. Leave blank to render `tx_hash` as plain text.	`https://testnet.xrpl.org/transactions`

Testing

Backend unit + integration tests

PostgreSQL is not required — the suite uses test fixtures.

cd backend
source .venv/bin/activate
pytest tests/

The suite under backend/tests/ covers:

Policy engine and authorization decisions (test_compliance.py, test_provider_compliance.py)
Proof Bundle issuance, signature, and expiry (test_api.py)
Each provider type, including HTTP sanctions, KYC upstream assertions, and reserve attestations (test_http_sanctions_provider.py, test_kyc_upstream_assertion.py, test_reserve_attestation.py, test_providers.py)
Settlement verification reason codes and edge cases (test_settlement_reason_codes.py, test_settlement_service.py)
XRPL integration paths (test_xrpl_integration_real.py)

Real XRPL testnet integration tests

Real XRPL integration tests are opt-in and skipped by default. To run them, set RUN_XRPL_INTEGRATION_TESTS:

RUN_XRPL_INTEGRATION_TESTS=true pytest backend/tests/test_xrpl_integration_real.py

These tests submit and verify real transactions on the XRPL testnet. They require:

A funded XRPL testnet signer seed (e.g. XRPL_SIGNER_SEED)
XRPL_RPC_URL pointing at a reachable XRPL JSON-RPC endpoint
A configured database (DATABASE_URL must be set and reachable)

⚠️ WARNING: Never set XRPL_SIGNER_SEED to a mainnet seed. These tests submit real transactions and are intended for the XRPL testnet only.

End-to-end roundtrip script

cd backend
python3 scripts/xrpl_testnet_roundtrip.py

This script submits a real testnet Payment carrying a CompliGate bundle_hash in a memo, fetches the transaction back, and runs CompliGate's settlement verification against it.

Frontend tests and build

cd frontend
npm test          # vitest
npm run build

Manual smoke test

After uvicorn is running:

curl http://localhost:8000/health → {"status": "ok"}
curl http://localhost:8000/public-key → returns Ed25519 public key.
POST /v1/permit → receive Proof Bundle.
POST /v1/verify → confirm signature + expiry.
Submit XRPL testnet payment with bundle_hash in memo.
POST /v1/settlement/verify with the resulting tx_hash → verification result.

Proof Artifact Example

{
  "module": "CompliGate",
  "entity_id": "XRPL_TX_HASH",
  "rule_version_used": "COMPLIGATE_XRPL_MVP_V1",
  "decision_result": "SETTLED_COMPLIANT",
  "evaluation_context": {
    "xrpl_network": "testnet",
    "tx_hash": "XRPL_TX_HASH",
    "ledger_index": 123456,
    "memo_bundle_hash": "abc123",
    "memo_match": true,
    "sanctions": {
      "provider": "mock_trm",
      "decision": "pass",
      "evidence_reference": "mock:rAddress:timestamp"
    }
  },
  "reason_codes": [
    "XRPL_TX_FOUND",
    "XRPL_TX_VALIDATED",
    "BUNDLE_HASH_MEMO_MATCHED",
    "SETTLEMENT_VERIFIED"
  ],
  "timestamp": 1700000000,
  "bundle_hash": "abc123",
  "anchor_metadata": {
    "network": "xrpl-testnet",
    "tx_hash": "XRPL_TX_HASH",
    "ledger_index": 123456
  }
}

Values shown are illustrative; real proof artifacts are generated by the backend.

For Reviewers

If you are reviewing CompliGate for XRPL ecosystem alignment, the key things to verify are:

Does the backend submit a real XRPL testnet transaction?
Does the transaction memo include the CompliGate bundle_hash?
Can the backend fetch the transaction by tx_hash?
Does settlement verification confirm the memo match?
Does the proof artifact reference the real tx_hash and ledger_index?
Are mock compliance providers clearly labeled?

This project is intentionally honest about MVP boundaries.

Roadmap

MVP / Current

Real XRPL testnet roundtrip
Permit generation
Memo-linked bundle_hash
Settlement verification
Proof artifact generation
mock_trm provider abstraction

Future

Institution-hosted deployment model
XRPL issuer workflow integration
Policy pack versioning for GENIUS / CLARITY / tokenization rules
Multi-chain support

Contact

CompliGate is developed by CompliLedger.

Issues & discussion: https://github.com/Compliledger/CompliGate/issues
Security reports: please open a private security advisory via this repository.
General contact / partnership inquiries: open a GitHub issue and a maintainer will follow up.

License: TBD.

Name		Name	Last commit message	Last commit date
Latest commit History 571 Commits
backend		backend
docs/images		docs/images
frontend		frontend
.dockerignore		.dockerignore
.gitignore		.gitignore
DEMO_GUIDE.md		DEMO_GUIDE.md
Dockerfile		Dockerfile
README.md		README.md
railway.env.example		railway.env.example
railway.json		railway.json
railway.toml		railway.toml
test-live.js		test-live.js

Folders and files

Latest commit

History

Repository files navigation

CompliGate

Deterministic Compliance Authorization for XRPL Transactions

Executive Summary

Why XRPL Needs This

Problem → Solution

Demo Flow

Visual Demo

Architecture

Current Capabilities

Current Status and Limitations

Quickstart

Backend

Frontend

Database

End-to-end XRPL testnet roundtrip (optional)

API Endpoints

Environment Variables

Testing

Backend unit + integration tests

Real XRPL testnet integration tests

End-to-end roundtrip script

Frontend tests and build

Manual smoke test

Proof Artifact Example

For Reviewers

Roadmap

MVP / Current

Next

Future

Contact

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages