@gtcx/protocol-tradepass

Universal identity, credential, and verification protocol for the GTCX ecosystem.

Overview

TradePass provides decentralized identity (W3C DID), verifiable credentials (W3C VC), and a predicate-based claim model for global commodity trade. It enables any entity, asset, or transaction to be verified with cryptographic proof. The protocol supports 12 operator credential types, offline operation for up to 45 days, and selective disclosure via BBS+ signatures.

Key Concepts

• DID Identity -- Self-sovereign W3C Decentralized Identifiers (did:gtcx:tp_<hash>) with biometric binding and role-based access.
• Biometric Keygen -- HKDF-derived keys bound to biometric hashes and device identifiers.
• Verifiable Credentials -- Credentials for all 12 operator types (Producer, Aggregator, Vault, Refiner, Buyer, etc.) with full lifecycle management.
• Predicates and Claims -- Predicates define what can be verified (80+ types across 9 domains); claims are specific assertions with evidence, confidence scores, and cryptographic proof.
• Composite Predicates -- Simple predicates compose into complex verification bundles (e.g., Deal Due Diligence = KYC + Origin + Sanctions + Quality + Custody).
• TradeCV -- Portable reputation credential capturing a producer's verifiable transaction history and milestone progression.
• Confidence Scoring -- Every claim includes a weighted confidence score derived from evidence strength, attestor trust, temporal decay, and corroboration.

Usage

import {
  createDID,
  issueCredential,
  verifyCredential,
  createClaimService,
  createPredicateRegistry,
  evaluateComposite,
} from '@gtcx/protocol-tradepass';

// Create a decentralized identity
const did = createDID({ role: 'producer', region: 'gh-ashanti' });

// Issue a verifiable credential
const credential = issueCredential({ subject: did.id, type: 'ProducerID' });

// Evaluate composite compliance
const result = evaluateComposite(COMMODITY_DEAL_DUE_DILIGENCE, claims);

API

Identity and Credentials

• createDID -- Create a new decentralized identifier
• issueCredential / verifyCredential -- Issue and verify W3C verifiable credentials
• createIdentityStore -- Persistent identity management
• deriveBiometricKey -- Derive HKDF key material from biometric enrollment + device binding

Roles and Permissions

• assignRole / revokeRole -- Manage operator roles (producer, vault, refiner, buyer, etc.)
• checkPermission -- Evaluate role-based permissions against the capability matrix
• createTradePassPEP / tradePassRolesToPolicyRules -- Auth adapter for @gtcx/auth

Predicate Engine

• createPredicateRegistry -- Registry for predicate definitions
• PREDICATE_SEEDS -- Built-in predicate definitions (80+)
• createClaimService -- Create, attest, and manage claim lifecycle
• calculateConfidence / getAttestorTrustScore / calculateTemporalDecay -- Confidence scoring
• validateEvidence / calculateEvidenceStrength -- Evidence validation
• evaluateComposite / COMMODITY_DEAL_DUE_DILIGENCE -- Composite predicate evaluation

Trust and Infrastructure

• calculateTrustScore -- Compute trust scores for attestors
• createEventLog -- Immutable event log with hash chain integrity
• createOfflineQueue -- Offline operation support (up to 45 days)

Specification

See SPEC.md for the full protocol specification.

Persistence

• Postgres adapters: postgres-identity-store.ts
• Offline queue: offline-queue.ts — syncs claims and attestations when connectivity returns

Testing

pnpm vitest run protocols/tradepass/

**Coverage summary**: 34 test files, ~925 tests

License

BSL 1.1 -- converts to Apache 2.0 on January 1, 2030.