Voltar para Documentação

Docs Técnicas

atlas-kyc

atlas-kyc is the workspace crate for portable KYC artifacts and supporting proof material. It defines the signed portable KYC envelope, the cleartext payload it carries, the evidence manifest model, and the Ed25519 signing and verification logic used around those artifacts.

O conteúdo abaixo vem das fontes técnicas do repositório e é prerenderizado no site para leitura direta por pessoas, crawlers e agentes.

Summary

atlas-kyc is the workspace crate for portable KYC artifacts and supporting proof material. It defines the signed portable KYC envelope, the cleartext payload it carries, the evidence manifest model, and the Ed25519 signing and verification logic used around those artifacts.

Unlike atlas-common, this crate is focused and self-contained. It does not define the ledger-side KYC registry model. That on-chain record shape lives in atlas-common::schemas::kyc, while atlas-kyc handles the off-chain or cross-system proof objects that surround issuance and verification.

Why This Crate Exists

  • isolate portable KYC issuance and verification logic from node and wallet code
  • keep evidence hashing and Merkle helpers in one place
  • give admin and wallet surfaces one shared envelope format
  • separate portable proof artifacts from on-chain KYC registry state

Current Role In The Workspace

atlas-kyc currently owns four related pieces:

  1. PortableKyc, the signed portable certificate envelope
  2. KycPayload, the cleartext identity payload carried inside the envelope
  3. evidence models and Merkle hashing helpers
  4. Ed25519 issue/verify functions for the portable envelope

In the current workspace, the main operational flow is:

atlas-node-admin issues and validates portable KYC artifacts, and atlas-wallet verifies them on import.

Public Surface

Top-Level Modules

  • credential
  • crypto
  • evidence
  • portable

Important Types

  • PortableKyc
  • KycPayload
  • EvidenceItem
  • EvidenceManifest
  • LivenessEvidence
  • Credential

Important Functions

  • issue_portable_kyc
  • verify_portable_kyc
  • hash_evidence_leaf
  • populate_merkle_leaves
  • compute_merkle_root
  • compute_manifest_hash

Important Errors

  • KycCryptoError
  • EvidenceError

Key Modules

  • `lib.rs`: crate export surface and primary reexports
  • `portable.rs`: canonical portable KYC envelope and cleartext payload
  • `crypto.rs`: issue and verify flow for signed portable KYC artifacts
  • `evidence.rs`: evidence item model, Merkle leaf population, Merkle root generation, and manifest hashing
  • `credential.rs`: simpler credential struct with placeholder sign and verify behavior

Inputs And Outputs

Inputs

  • issuer signing keys
  • user and issuer wallet addresses
  • cleartext KYC payloads
  • optional institution metadata for the issuer
  • optional evidence attachments and liveness records

Outputs

  • signed portable KYC envelopes
  • verified cleartext KYC payloads
  • evidence leaves with deterministic hashes
  • Merkle roots and manifest hashes for evidence bundles

Internal Dependencies

Workspace Dependencies

  • none

atlas-kyc is another low-level crate. It does not depend on atlas-common.

External Dependencies That Shape The Design

  • serde and serde_json for envelope serialization
  • ed25519-dalek for signing and verification
  • sha2 for deterministic hashing
  • hex for self-contained signature and hash encoding

Used By

These packages depend directly on atlas-kyc today:

  • atlas-bank
  • atlas-wallet
  • atlas-ledger
  • atlas-node
  • atlas-node-admin

Observed runtime usage is concentrated in a smaller set:

  • `handlers/kyc.rs`: issues portable KYC artifacts and verifies them before registering proof on-chain
  • `handlers/workflow.rs`: verifies portable KYC and derives evidence data during KYC workflow approval
  • `wasm.rs`: verifies imported portable KYC inside the wallet Wasm boundary

The root Cargo dependency in some other crates appears broader than the currently observed direct source usage.

Testing

The crate relies on module-local tests:

  • JSON roundtrips for PortableKyc
  • metadata defaults for KycPayload
  • issue and verify happy-path coverage
  • tamper detection for signed payloads
  • invalid signature format handling
  • deterministic evidence leaf hashing
  • deterministic Merkle root and manifest hash computation

There do not appear to be standalone integration tests for this crate. The cross-crate validation happens mainly through admin and wallet consumers.

Risks Or Design Tension

Split KYC Model

The workspace has two KYC layers:

  • atlas-common::schemas::kyc for on-chain registration records
  • atlas-kyc for portable proof artifacts

That split is reasonable, but it means readers need to understand that atlas-kyc is not the whole KYC domain.

Placeholder Credential Type

`credential.rs` exposes a Credential type with placeholder sign and is_valid_signature behavior. The production-grade flow appears to be the PortableKyc path in crypto.rs, not this simpler credential object.

Canonical Signing Format Is Hand-Assembled

crypto.rs constructs canonical signable bytes by concatenating fields into a string. That is simple and deterministic, but brittle if the envelope evolves. Any field-order drift would break compatibility.

Open Questions

  • should Credential remain public if the real system standard is PortableKyc
  • should the canonical signing format move from string concatenation to a dedicated versioned canonical encoder
  • should expiry be enforced in verification, or is that intentionally left to higher layers
  • should evidence models stay here long term, or split into a dedicated KYC workflow crate if the workflow grows further

Relevant Files

  • `Cargo.toml`
  • `lib.rs`
  • `portable.rs`
  • `crypto.rs`
  • `evidence.rs`
  • `credential.rs`
  • `handlers/kyc.rs`
  • `handlers/workflow.rs`
  • `wasm.rs`