soulprint-network 0.2.3 → 0.3.0

package/dist/blockchain/blockchain-client.d.ts

@@ -0,0 +1,118 @@
+/**
+ * blockchain-client.ts — Cliente para interactuar con los contratos Soulprint on-chain.
+ *
+ * MODO HÍBRIDO:
+ * El nodo validador opera en dos modos:
+ *
+ * 1. ONLINE (blockchain activo):
+ *    - nullifierUsed()     → consulta SoulprintRegistry on-chain
+ *    - registerIdentity()  → registra nullifier + ZK proof on-chain
+ *    - attest()            → escribe attestation en AttestationLedger
+ *    - getReputation()     → lee score on-chain
+ *
+ * 2. OFFLINE (sin conexión RPC):
+ *    - Fallback a stores locales (nullifiers.json, repStore.json)
+ *    - Los datos se sincronizan con blockchain cuando vuelve la conexión
+ *    - Garantiza disponibilidad incluso sin internet
+ *
+ * CONFIGURACIÓN:
+ *   SOULPRINT_RPC_URL=https://sepolia.base.org
+ *   SOULPRINT_PRIVATE_KEY=0x...
+ *   SOULPRINT_REGISTRY_ADDR=0x...
+ *   SOULPRINT_LEDGER_ADDR=0x...
+ */
+export interface BlockchainConfig {
+    rpcUrl: string;
+    privateKey: string;
+    registryAddr: string;
+    ledgerAddr: string;
+    validatorRegAddr?: string;
+    protocolHash: string;
+}
+export interface OnChainReputation {
+    score: number;
+    totalPositive: number;
+    totalNegative: number;
+    lastUpdated: number;
+    source: "blockchain" | "local";
+}
+export declare function loadBlockchainConfig(): BlockchainConfig | null;
+export declare class SoulprintBlockchainClient {
+    private config;
+    private provider;
+    private signer;
+    private registry;
+    private ledger;
+    private validatorReg;
+    private connected;
+    constructor(config: BlockchainConfig);
+    /**
+     * Inicializa la conexión con la blockchain.
+     * Lanza error si ethers no está disponible (opcional dependency).
+     */
+    connect(): Promise<boolean>;
+    get isConnected(): boolean;
+    /**
+     * Verifica si un nullifier ya está registrado (anti-sybil on-chain).
+     */
+    isNullifierUsed(nullifier: string): Promise<boolean | null>;
+    /**
+     * Registra una identidad on-chain con ZK proof.
+     * @returns txHash o null si falla
+     */
+    registerIdentity(params: {
+        nullifier: string;
+        did: string;
+        documentVerified: boolean;
+        faceVerified: boolean;
+        zkProof: {
+            a: [bigint, bigint];
+            b: [[bigint, bigint], [bigint, bigint]];
+            c: [bigint, bigint];
+            inputs: [bigint, bigint];
+        };
+    }): Promise<string | null>;
+    /**
+     * Retorna el identity score on-chain de un DID.
+     */
+    getIdentityScore(did: string): Promise<number | null>;
+    /**
+     * Escribe una attestation on-chain.
+     * @returns txHash o null si falla
+     */
+    attest(params: {
+        issuerDid: string;
+        targetDid: string;
+        value: 1 | -1;
+        context: string;
+        signature: string;
+    }): Promise<string | null>;
+    /**
+     * Obtiene la reputación on-chain de un DID.
+     */
+    getReputation(did: string): Promise<OnChainReputation | null>;
+    /**
+     * Score total on-chain (identity + reputation).
+     */
+    getTotalScore(did: string): Promise<number | null>;
+    /**
+     * Registra este nodo en el ValidatorRegistry on-chain.
+     */
+    registerNode(params: {
+        url: string;
+        did: string;
+        protocolHash: string;
+    }): Promise<string | null>;
+    /**
+     * Envía heartbeat on-chain.
+     */
+    heartbeat(did: string, totalVerified: number): Promise<void>;
+    /**
+     * Lista nodos activos on-chain (para peer discovery).
+     */
+    getActiveNodes(): Promise<Array<{
+        url: string;
+        did: string;
+        compatible: boolean;
+    }>>;
+}

package/dist/blockchain/blockchain-client.js

@@ -0,0 +1,280 @@
+/**
+ * blockchain-client.ts — Cliente para interactuar con los contratos Soulprint on-chain.
+ *
+ * MODO HÍBRIDO:
+ * El nodo validador opera en dos modos:
+ *
+ * 1. ONLINE (blockchain activo):
+ *    - nullifierUsed()     → consulta SoulprintRegistry on-chain
+ *    - registerIdentity()  → registra nullifier + ZK proof on-chain
+ *    - attest()            → escribe attestation en AttestationLedger
+ *    - getReputation()     → lee score on-chain
+ *
+ * 2. OFFLINE (sin conexión RPC):
+ *    - Fallback a stores locales (nullifiers.json, repStore.json)
+ *    - Los datos se sincronizan con blockchain cuando vuelve la conexión
+ *    - Garantiza disponibilidad incluso sin internet
+ *
+ * CONFIGURACIÓN:
+ *   SOULPRINT_RPC_URL=https://sepolia.base.org
+ *   SOULPRINT_PRIVATE_KEY=0x...
+ *   SOULPRINT_REGISTRY_ADDR=0x...
+ *   SOULPRINT_LEDGER_ADDR=0x...
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// ── ABI mínimos para interactuar con los contratos ────────────────────────────
+// Solo las funciones que usa el nodo validador
+const REGISTRY_ABI = [
+    "function isRegistered(bytes32 nullifier) view returns (bool)",
+    "function identityScore(string did) view returns (uint8)",
+    "function registerIdentity(bytes32 nullifier, string did, bool docVerified, bool faceVerified, uint256[2] a, uint256[2][2] b, uint256[2] c, uint256[2] inputs) external",
+    "event IdentityRegistered(bytes32 indexed nullifier, string indexed did, uint8 identityScore, uint64 timestamp)",
+    "function PROTOCOL_HASH() view returns (bytes32)",
+];
+const LEDGER_ABI = [
+    "function attest(string issuerDid, string targetDid, int8 value, string context, bytes signature) external",
+    "function getTotalScore(string did) view returns (uint16)",
+    "function getReputation(string did) view returns (tuple(int16 score, uint16 totalPositive, uint16 totalNegative, uint64 lastUpdated))",
+    "function getAttestations(string did) view returns (tuple(string issuerDid, string targetDid, int8 value, string context, uint64 timestamp, bytes signature)[])",
+    "function canAttest(string issuerDid, string targetDid) view returns (bool allowed, uint64 nextTs)",
+    "event AttestationRecorded(string indexed targetDid, string issuerDid, int8 value, string context, uint64 timestamp)",
+];
+const VALIDATOR_REG_ABI = [
+    "function registerNode(string url, string did, bytes32 protocolHash) external",
+    "function heartbeat(string did, uint32 totalVerified) external",
+    "function getActiveNodes() view returns (tuple(string url, string did, bytes32 protocolHash, uint64 registeredAt, uint64 lastSeen, uint32 totalVerified, bool active, bool compatible)[])",
+    "function PROTOCOL_HASH() view returns (bytes32)",
+];
+// ── Load config from env + deployments ───────────────────────────────────────
+export function loadBlockchainConfig() {
+    const rpcUrl = process.env.SOULPRINT_RPC_URL;
+    const privateKey = process.env.SOULPRINT_PRIVATE_KEY;
+    const network = process.env.SOULPRINT_NETWORK ?? "base-sepolia";
+    if (!rpcUrl || !privateKey)
+        return null;
+    // Buscar direcciones en deployments/
+    const deploymentsDir = join(__dirname, "..", "..", "blockchain", "deployments");
+    const deployFile = join(deploymentsDir, `${network}.json`);
+    if (!existsSync(deployFile)) {
+        console.warn(`[blockchain] No deployment found for ${network}. Run: npx hardhat run scripts/deploy.ts --network ${network}`);
+        return null;
+    }
+    const deployment = JSON.parse(readFileSync(deployFile, "utf8"));
+    return {
+        rpcUrl,
+        privateKey,
+        registryAddr: deployment.contracts.SoulprintRegistry,
+        ledgerAddr: deployment.contracts.AttestationLedger,
+        validatorRegAddr: deployment.contracts.ValidatorRegistry,
+        protocolHash: deployment.protocolHash,
+    };
+}
+// ── Blockchain Client ─────────────────────────────────────────────────────────
+export class SoulprintBlockchainClient {
+    config;
+    provider = null;
+    signer = null;
+    registry = null;
+    ledger = null;
+    validatorReg = null;
+    connected = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Inicializa la conexión con la blockchain.
+     * Lanza error si ethers no está disponible (opcional dependency).
+     */
+    async connect() {
+        try {
+            // @ts-ignore — ethers is an optional peer dependency
+            const ethersModule = await import("ethers").catch(() => null);
+            if (!ethersModule)
+                return false;
+            const ethers = ethersModule.ethers;
+            this.provider = new ethers.JsonRpcProvider(this.config.rpcUrl);
+            this.signer = new ethers.Wallet(this.config.privateKey, this.provider);
+            this.registry = new ethers.Contract(this.config.registryAddr, REGISTRY_ABI, this.signer);
+            this.ledger = new ethers.Contract(this.config.ledgerAddr, LEDGER_ABI, this.signer);
+            if (this.config.validatorRegAddr) {
+                this.validatorReg = new ethers.Contract(this.config.validatorRegAddr, VALIDATOR_REG_ABI, this.signer);
+            }
+            // Verificar que el contrato tiene el mismo PROTOCOL_HASH
+            const onChainHash = await this.registry.PROTOCOL_HASH();
+            if (onChainHash.toLowerCase() !== this.config.protocolHash.toLowerCase()) {
+                console.error(`[blockchain] ❌ PROTOCOL_HASH mismatch!`);
+                console.error(`  On-chain:  ${onChainHash}`);
+                console.error(`  Expected:  ${this.config.protocolHash}`);
+                return false;
+            }
+            this.connected = true;
+            const network = await this.provider.getNetwork();
+            console.log(`[blockchain] ✅ Connected to chain ${network.chainId} (${network.name})`);
+            console.log(`[blockchain]    Registry:  ${this.config.registryAddr}`);
+            console.log(`[blockchain]    Ledger:    ${this.config.ledgerAddr}`);
+            return true;
+        }
+        catch (err) {
+            console.warn(`[blockchain] Offline mode — ${err.message?.slice(0, 60)}`);
+            return false;
+        }
+    }
+    get isConnected() { return this.connected; }
+    // ── Registry ───────────────────────────────────────────────────────────────
+    /**
+     * Verifica si un nullifier ya está registrado (anti-sybil on-chain).
+     */
+    async isNullifierUsed(nullifier) {
+        if (!this.connected)
+            return null;
+        try {
+            return await this.registry.isRegistered(nullifier);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Registra una identidad on-chain con ZK proof.
+     * @returns txHash o null si falla
+     */
+    async registerIdentity(params) {
+        if (!this.connected)
+            return null;
+        try {
+            const tx = await this.registry.registerIdentity(params.nullifier, params.did, params.documentVerified, params.faceVerified, params.zkProof.a, params.zkProof.b, params.zkProof.c, params.zkProof.inputs);
+            const receipt = await tx.wait();
+            console.log(`[blockchain] ✅ Identity registered | tx: ${receipt.hash}`);
+            return receipt.hash;
+        }
+        catch (err) {
+            console.error(`[blockchain] registerIdentity failed: ${err.message?.slice(0, 80)}`);
+            return null;
+        }
+    }
+    /**
+     * Retorna el identity score on-chain de un DID.
+     */
+    async getIdentityScore(did) {
+        if (!this.connected)
+            return null;
+        try {
+            return Number(await this.registry.identityScore(did));
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Attestation Ledger ─────────────────────────────────────────────────────
+    /**
+     * Escribe una attestation on-chain.
+     * @returns txHash o null si falla
+     */
+    async attest(params) {
+        if (!this.connected)
+            return null;
+        try {
+            const tx = await this.ledger.attest(params.issuerDid, params.targetDid, params.value, params.context, params.signature);
+            const receipt = await tx.wait();
+            console.log(`[blockchain] ✅ Attestation recorded | tx: ${receipt.hash}`);
+            return receipt.hash;
+        }
+        catch (err) {
+            // Manejar CooldownActive gracefully
+            if (err.message?.includes("CooldownActive")) {
+                console.warn(`[blockchain] Attestation cooldown active for ${params.issuerDid} → ${params.targetDid}`);
+            }
+            else {
+                console.error(`[blockchain] attest failed: ${err.message?.slice(0, 80)}`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Obtiene la reputación on-chain de un DID.
+     */
+    async getReputation(did) {
+        if (!this.connected)
+            return null;
+        try {
+            const rep = await this.ledger.getReputation(did);
+            return {
+                score: Number(rep.score),
+                totalPositive: Number(rep.totalPositive),
+                totalNegative: Number(rep.totalNegative),
+                lastUpdated: Number(rep.lastUpdated),
+                source: "blockchain",
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Score total on-chain (identity + reputation).
+     */
+    async getTotalScore(did) {
+        if (!this.connected)
+            return null;
+        try {
+            return Number(await this.ledger.getTotalScore(did));
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Validator Registry ─────────────────────────────────────────────────────
+    /**
+     * Registra este nodo en el ValidatorRegistry on-chain.
+     */
+    async registerNode(params) {
+        if (!this.connected || !this.validatorReg)
+            return null;
+        try {
+            const tx = await this.validatorReg.registerNode(params.url, params.did, params.protocolHash);
+            const receipt = await tx.wait();
+            console.log(`[blockchain] ✅ Node registered | tx: ${receipt.hash}`);
+            return receipt.hash;
+        }
+        catch (err) {
+            if (err.message?.includes("AlreadyRegistered")) {
+                console.log(`[blockchain] Node already registered`);
+            }
+            else {
+                console.error(`[blockchain] registerNode failed: ${err.message?.slice(0, 80)}`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Envía heartbeat on-chain.
+     */
+    async heartbeat(did, totalVerified) {
+        if (!this.connected || !this.validatorReg)
+            return;
+        try {
+            const tx = await this.validatorReg.heartbeat(did, totalVerified);
+            await tx.wait();
+        }
+        catch { /* non-critical */ }
+    }
+    /**
+     * Lista nodos activos on-chain (para peer discovery).
+     */
+    async getActiveNodes() {
+        if (!this.connected || !this.validatorReg)
+            return [];
+        try {
+            const nodes = await this.validatorReg.getActiveNodes();
+            return nodes.map((n) => ({
+                url: n.url,
+                did: n.did,
+                compatible: n.compatible,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/consensus/attestation-consensus.d.ts

@@ -0,0 +1,114 @@
+/**
+ * attestation-consensus.ts — Attestations firmadas + propagadas por P2P.
+ *
+ * DISEÑO (sin EVM):
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Las attestations NO necesitan consenso multi-ronda porque:
+ *   1. Están firmadas con Ed25519 (no repudiables)
+ *   2. El issuer es verificable (score >= MIN_ATTESTER_SCORE)
+ *   3. El anti-farming es local + determinista
+ *
+ * FLUJO:
+ *   Issuer firma attest → broadcast a red → cada nodo valida firma + cooldown
+ *   → si válido: guarda en store + propaga → estado eventualmente consistente
+ *
+ * ANTI-FARMING ON-CHAIN (sin EVM):
+ *   • Map<issuer:target → lastTs> con cooldown de 24h
+ *   • Anti-farming de soulprint-core (FARMING_RULES) para patrones robóticos
+ *   • FARMING_RULES Object.freeze → constantes inmutables
+ *
+ * CONSISTENCIA:
+ *   • Eventual: todos los nodos convergen al mismo estado en segundos
+ *   • Cada attest lleva firma + timestamp → reordenable en merge
+ *   • Sin conflictos: misma firma = misma attestation (idempotente)
+ */
+import { EventEmitter } from "node:events";
+export interface AttestationMsg {
+    type: "ATTEST";
+    issuerDid: string;
+    targetDid: string;
+    value: 1 | -1;
+    context: string;
+    ts: number;
+    protocolHash: string;
+    sig: string;
+}
+export interface AttestEntry {
+    issuerDid: string;
+    targetDid: string;
+    value: 1 | -1;
+    context: string;
+    ts: number;
+    sig: string;
+    msgHash: string;
+}
+export interface Reputation {
+    score: number;
+    totalPositive: number;
+    totalNegative: number;
+    lastUpdated: number;
+}
+export interface AttestationConsensusOptions {
+    selfDid: string;
+    sign: (data: string) => Promise<string>;
+    verify: (data: string, sig: string, did: string) => Promise<boolean>;
+    broadcast: (msg: AttestationMsg) => Promise<void>;
+    getScore: (did: string) => number;
+    storePath: string;
+    repStorePath: string;
+}
+export declare class AttestationConsensus extends EventEmitter {
+    private opts;
+    private history;
+    private reps;
+    private cooldowns;
+    private seen;
+    constructor(opts: AttestationConsensusOptions);
+    /**
+     * Emite una attestation desde este nodo.
+     * Firma, guarda localmente, y hace broadcast.
+     */
+    attest(params: {
+        issuerDid: string;
+        targetDid: string;
+        value: 1 | -1;
+        context: string;
+    }): Promise<AttestEntry>;
+    /**
+     * Procesa un mensaje ATTEST recibido de la red.
+     */
+    handleMessage(msg: AttestationMsg): Promise<void>;
+    /**
+     * Retorna la reputación de un DID.
+     */
+    getReputation(targetDid: string): Reputation;
+    /**
+     * Retorna el historial de attestations de un DID.
+     */
+    getHistory(targetDid: string): AttestEntry[];
+    /**
+     * Verifica si un par puede atestar ahora (no en cooldown).
+     */
+    canAttest(issuerDid: string, targetDid: string): {
+        allowed: boolean;
+        nextTs?: number;
+    };
+    /**
+     * Exporta estado para sync con nuevos nodos.
+     */
+    exportState(): {
+        history: Record<string, AttestEntry[]>;
+        reps: Record<string, Reputation>;
+    };
+    /**
+     * Importa estado de otro nodo al arrancar.
+     */
+    importState(state: {
+        history: Record<string, AttestEntry[]>;
+        reps: Record<string, Reputation>;
+    }): number;
+    private applyAttest;
+    private hashMsg;
+    private loadStores;
+    private saveStores;
+}