ConfidentialAuditv1.01
HomeInstallGitHubConsole
Docssolana-confidential-skill

Documentation

The auditor-side AML engine for Solana Token-2022 Confidential Transfers — how it runs, what it detects, the cryptography, and the API.

01

Overview

Confidential Transfers encrypt amounts on-chain with twisted-ElGamal + ZK proofs — exactly what regulated payments need, and exactly what blocks them, because a regulator can't see amounts. Solana ships the answer: a mint can carry a global auditor ElGamal key whose holder can decrypt every transfer amount for that mint. This skill is the tooling that operates that key: key setup → continuous decryption loop → AML engine → hashed reports. Privacy stays the default for everyone else, by cryptography, not policy.

02

How it runs

The compliance loop is observe → decrypt → assess → report → repeat:

  1. Observe — pull confidential transfers for one mint, oldest-first (RPC/Helius).
  2. Decrypt — the auditor ElGamal key recovers each amount. No account keys touched.
  3. Assess — deterministic AML rules score each amount against rolling state.
  4. Report — flags page out; a SHA-256 hashed, append-only report is emitted.

Termination is guaranteed by a BudgetLedger (caps + circuit breaker).

03

AML rules

These are precisely the patterns confidential transfers hide from the public chain — so only the auditor key holder can detect them. Pure functions of (transfer, rolling state, config); every rule ships an offline test.

sanctionedhighOFAC / denylisted counterparty on either side
thresholdhighSingle transfer at/above the CTR report line
structuringhighA big payment split into sub-threshold pieces (smurfing)
velocitymediumOut-volume or out-count beyond a per-window limit
concentrationmediumFunnel / mule — most volume to one counterparty
layeringmediumFunds received then forwarded fast (pass-through)
dormancymediumLong-idle account suddenly moves material funds
04

Cryptography

Real twisted-ElGamal over Ristretto255 (Solana's group), with a baby-step-giant-step discrete-log solver. The encrypt→decrypt round-trip is tested across the full 48-bit range, with semantic security and wrong-key-fails.

It decrypts real @solana/zk-sdk ciphertext: select convention: "solana" for Solana's exact scheme (amount·G = C − s·D) and layout: "lohi" for the production 16-bit-low + 32-bit-high split. Verified against bytes produced by the real Solana library — byte-identical to on-chain — using only this engine's crypto.

05

Guardrails

CT01 · Key custodyAuditor secret lives in HSM/TEE, loaded at runtime. Never logged, committed, or in client code.
CT02 · Trust boundaryOne loop ⇒ one mint ⇒ one key, one process. No shared decryptors.
CT03 · No silent skipsA failed decrypt/observe halts via the circuit breaker. Missing a transfer is worse than stopping.
CT04 · Raw amount hygieneDecrypted amounts live in memory only long enough to score; reports carry aggregates + flags.
CT05 · DeterminismAML rules are pure functions of (transfer, state, config). No clock/IO/randomness inside a rule.
CT06 · TerminationEvery loop carries a BudgetLedger — duration/iteration/RPC caps + error breaker.
CT07 · Report immutabilityReports are SHA-256 hashed over canonical body; append-only. Supersede, never edit.
CT08 · Block orderingProcess transfers oldest-first; the windowed detectors depend on it.
CT09 · Ciphertext layoutReal Solana lo(16)/hi(32) ElGamal split + zk-sdk decrypt convention, tested against real bytes.
06

Quick start

import {
  ConfidentialComplianceLoop, ComplianceEngine, BudgetLedger,
  defaultConfig, SplAuditorDecryptor,
} from "solana-confidential-compliance";

const loop = new ConfidentialComplianceLoop({
  mint, auditorPubkey,
  decryptor: new SplAuditorDecryptor({
    auditorElGamalSecret,        // from your HSM / TEE
    layout: "lohi", convention: "solana",   // real on-chain ciphertext
  }),
  engine: new ComplianceEngine(defaultConfig(6)),
  budget: new BudgetLedger({ maxDurationMs: 8 * 3600_000, maxConsecutiveErrors: 5 }),
  observe: fetchNewConfidentialTransfers,    // RPC / Helius, oldest-first
  onFlags: alertSink,
  onReport: persistImmutable,
});

await loop.run();
07

API surface

ConfidentialComplianceLoopobserve → decrypt → assess → report → repeat, budget-bounded
ComplianceEnginedeterministic AML engine over decrypted transfers
SplAuditorDecryptorreal decrypt; layout: limbed|lohi, convention: engine|solana
decryptSolanaAmountLoHidecrypt real @solana/zk-sdk lo/hi auditor ciphertext
BudgetLedgeriteration / time / RPC caps + circuit breaker
buildReportSHA-256 hashed, tamper-evident compliance report
defaultConfig(decimals)tunable AML thresholds for a mint
08

Skill modules

The skill is progressive — skill/SKILL.md routes to a module only when it's needed.

primer.mdCT + the auditor key from first principles →auditor-key-setup.mdcreate a mint with confidential transfers + auditor key →compliance-loop.mdarchitect & operate the monitoring loop →aml-rules.mdtune thresholds, add custom detection rules →decryption.mdwire real ElGamal + lo/hi + Solana-convention decrypt →integration-helius.mdfetch confidential transfers (poll or webhook) →reporting.mdemit hashed, regulator-facing reports →budget-and-stops.mdguarantee termination + circuit breaking →resources.mdofficial specs, SDKs, status, links →
Install the skillOpen the console