soulprint (Manuelariasfz)

🔐 灵魂印记

AI代理的去中心化KYC身份协议。

Soulprint让任何人工智能机器人都能证明它背后有一个经过验证的人——而不会透露这个人是谁。没有公司，没有服务器，也没有付费的API。只是加密证明。

 \](https://npmjs.com/package/soulprint) ](https://npmjs.com/package/soulprint-mcp) () ](https://npmjs.com/package/soulprint-network)

______________________________________________________________________

问题

人工智能代理代表人类行事：预订航班、调用API、做出决策。但没有任何服务可以知道机器人是合法的还是恶意的。没有问责制。

Soulprint解决了这个问题 通过将每个机器人与经过验证的人类身份联系起来——加密、保密，没有任何中央权威。

______________________________________________________________________

运作原理

1. User runs: npx soulprint verify-me --selfie me.jpg --document cedula.jpg
              ↓
2. LOCAL (on-device, nothing leaves your machine):
   • Tesseract OCR reads the cedula (Colombian ID)
   • InsightFace matches your face to the document photo
   • Poseidon hash derives a unique nullifier from (cedula + birthdate + face_key)
   • ZK proof generated: "I verified my identity" without revealing any data
   • Photos deleted from memory
              ↓
3. ZK proof + SPT broadcast to validator node (verifies in 25ms, offline)
              ↓
4. Soulprint Token (SPT) stored in ~/.soulprint/token.spt — valid 24h
              ↓
5. Any MCP server or API verifies in " }
  }
}

或者在HTTP标头中： X-Soulprint:

使用DPoP--防止令牌被盗（v0.3.8）

// ── Server side — strict mode ─────────────────────────────────────
server.use(soulprint({ minScore: 60, requireDPoP: true }));
// → 401 { error: "dpop_required" } if no proof header

// ── Client side — sign every request ─────────────────────────────
import { signDPoP, serializeDPoP } from "soulprint-core";

// Load your keypair (never transmit the private key)
const { privateKey, did } = loadKeypair();
const myToken = "";

// Before each tool call:
const proof = signDPoP(privateKey, did, "POST", toolUrl, myToken);
headers["X-Soulprint"]       = myToken;
headers["X-Soulprint-Proof"] = serializeDPoP(proof);

被盗的SPT 无用的 没有私钥。证据是：

• 每个请求唯一（随机随机数）
• URL+方法绑定（无MITM）
• 5分钟后过期
• 哈希绑定到特定令牌

______________________________________________________________________

保护任何REST API

import express from "express";
import { soulprint } from "soulprint-express";

const app = express();

// Protect entire API
app.use(soulprint({ minScore: 40 }));

// Strict: require DPoP proof (prevent token theft)
app.use(soulprint({ minScore: 65, requireDPoP: true }));

// Or specific routes
app.post("/sensitive", soulprint({ require: ["DocumentVerified", "FaceMatch"] }), handler);

// Access the verified identity + check if token was auto-renewed
app.get("/me", soulprint({ minScore: 20 }), (req, res) => {
  const renewedToken = res.getHeader("X-Soulprint-Token-Renewed");
  res.json({
    nullifier: req.soulprint!.nullifier,  // unique per human, no PII
    score:     req.soulprint!.score,
    ...(renewedToken ? { token_renewed: renewedToken } : {}),
  });
});

快速

import { soulprintFastify } from "soulprint-express";

await fastify.register(soulprintFastify, { minScore: 60 });

fastify.get("/me", async (request) => ({
  nullifier: request.soulprint?.nullifier,
}));

运行验证器节点

任何人都可以运行验证器节点。每个节点运行 两个堆栈同时：HTTP（端口4888）+libp2p P2P（端口6888）。

# Arranque simple — mDNS descubre nodos en la misma LAN automáticamente
npx soulprint node

# Con bootstrap nodes para conectar a la red global
SOULPRINT_BOOTSTRAP=/ip4/x.x.x.x/tcp/6888/p2p/12D3KooW... \
npx soulprint node

输出特殊：

🌐 Soulprint Validator Node v0.2.2
   Node DID:     did:key:z6Mk...
   Listening:    http://0.0.0.0:4888

🔗 P2P activo
   Peer ID:    12D3KooW...
   Multiaddrs: /ip4/x.x.x.x/tcp/6888/p2p/12D3KooW...
   Gossip:     HTTP fallback + GossipSub P2P
   Discovery:  mDNS (+ DHT si hay bootstraps)

节点API：

GET  /info              — node info + p2p stats (peer_id, peers, multiaddrs)
POST /verify            — verify ZK proof + co-sign SPT
POST /reputation/attest — issue +1/-1 attestation (propagado via GossipSub)
GET  /reputation/:did   — get bot reputation
GET  /nullifier/:hash   — check anti-Sybil registry

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────────┐
│  Layer 4 — SDKs (soulprint-mcp, express)      ✅ Done  │
├─────────────────────────────────────────────────────────┤
│  Layer 3 — Validator Nodes (HTTP + anti-Sybil)  ✅ Done │
├─────────────────────────────────────────────────────────┤
│  Layer 2 — ZK Proofs (Circom + snarkjs)         ✅ Done │
├─────────────────────────────────────────────────────────┤
│  Layer 1 — Local Verification (Face + OCR)      ✅ Done │
└─────────────────────────────────────────────────────────┘

按需ML模型

AI模型是 从不坚持跑步:

Idle state:       ~8MB RAM   (only the CLI)
During verify:    ~200MB RAM (InsightFace subprocess spawned)
After verify:     ~8MB RAM   (subprocess exits → memory freed)

______________________________________________________________________

包裹

______________________________________________________________________

ZK电路

Soulprint的核心是 电路板 电路证明：

*“我知道雪松编号+出生日期+面部按键，这样*\ *Poseidon(cedula, birthdate, face_key) == nullifier*\ *并且该雪松在有效的Registraduría范围内”*

不透露任何私人信息。

电路统计数据：

• 844非线性约束
• 4个私人输入（雪松、出生日期、脸钥匙、盐）
• 2个公共输入（无效器、context_tag）
• 证明生成：笔记本电脑上约600ms
• 验证：离线约25ms

______________________________________________________________________

灵魂印记代币（SPT）

一个base64url编码的签名JWT。 不包含PII。

{
  "sip":         "1",
  "did":         "did:key:z6MkhaXgBZ...",
  "score":       45,
  "level":       "KYCFull",
  "country":     "CO",
  "credentials": ["DocumentVerified", "FaceMatch"],
  "nullifier":   "0x7090787188...",
  "zkp":         "eyJwIjp7InBpX2EiOlsi...",
  "issued":      1740000000,
  "expires":     1740086400,
  "sig":         "ed25519_signature"
}

______________________________________________________________________

信任评分

Credential          | Score
--------------------|-------
EmailVerified       | +10
PhoneVerified       | +15
GitHubLinked        | +20
DocumentVerified    | +25
FaceMatch           | +20
BiometricBound      | +10
                    |
KYCFull (doc+face)  |  45/100

服务选择自己的阈值：

soulprint({ minScore: 20 })   // email verified is enough
soulprint({ minScore: 45 })   // require doc + face KYC
soulprint({ minScore: 80 })   // require full biometric + extra

______________________________________________________________________

防Sybil保护

无效者来源于 生物识别+文档数据:

nullifier = Poseidon(cedula_number, birthdate, face_key)
face_key  = Poseidon(quantized_face_embedding[0..31])

• 同一个人，不同的设备→ 同一无效者
• 不同的人，同样的雪松→ 不同的无效者 （面部不匹配）
• 个人注册两次→ 无效器已存在→ 被验证器拒绝

______________________________________________________________________

支持的国家

______________________________________________________________________

开发环境

git clone https://github.com/manuelariasfz/soulprint
cd soulprint
pnpm install
pnpm build

运行集成测试

# ZK proof tests (no circuit compilation needed)
cd packages/zkp && node dist/prover.test.js

# Full integration tests
node -e "require('./packages/core/dist/index.js')"

编译ZK电路（仅限第一次）

pnpm --filter soulprint-zkp build:circuits

Python依赖关系

pip3 install insightface opencv-python-headless onnxruntime

______________________________________________________________________

信任评分——0到100

Total Score (0-100) = Identity (0-80) + Bot Reputation (0-20)

身份凭证（最多80分）：

访问级别：

______________________________________________________________________

机器人信誉（v0.1.3）

声誉层（0-20分）随着时间的推移从行为层面建立起来 证明 由经过验证的服务发布。

Reputation starts at: 10 (neutral)
Verified service issues +1  →  goes up  (max 20)
Verified service issues -1  →  goes down (min 0)

证明格式（Ed25519签名）：

interface BotAttestation {
  issuer_did: string;  // service DID (requires score >= 60 to issue)
  target_did: string;  // bot being rated
  value:      1 | -1;
  context:    string;  // "spam-detected", "normal-usage", "payment-completed"
  timestamp:  number;
  sig:        string;  // Ed25519 — bound to issuer_did
}

只有得分≥60的服务才能出具证明。 这可以防止低质量的服务在网络上玩游戏。

证明传播 所有验证器节点上的P2P 通过libp2p Gossip Sub（遗留节点有HTTP回退）。

______________________________________________________________________

反农业保护（v0.3.5）

声誉系统受到保护，不受点农的影响。 检测到农业→ 自动-1罚 （不仅仅是拒绝）。

所有验证器节点执行的规则(FARMING_RULES — Object.freeze):

______________________________________________________________________

生命生态系统--mcp哥伦比亚中心

mcp哥伦比亚中心 是 首次验证服务 在Soulprint生态系统中：

• 服务评分： 80（文件验证+FaceMatch+GitHubLinked+生物识别绑定）
• 汽车问题-1 当机器人发出垃圾邮件时（>5个请求/60s）
• 汽车问题+1 当机器人正常完成3个以上工具时
• 高级端点 trabajo_aplicar 要求得分≥40

npx -y mcp-colombia-hub

______________________________________________________________________

安全模型

______________________________________________________________________

路线图

✅ Phase 1 — Local verification (cedula OCR + face match + nullifier)
✅ Phase 2 — ZK proofs (Circom circuit + snarkjs prover/verifier)
✅ Phase 3 — Validator nodes (HTTP + ZK verify + anti-Sybil registry)
✅ Phase 4 — SDKs (soulprint-mcp, soulprint-express)
✅ Phase 5 — P2P network (libp2p v2 · Kademlia DHT + GossipSub + mDNS · soulprint-network@0.2.2)
✅ v0.3.7 — Challenge-Response peer integrity · snarkjs critical fix · SPT auto-renewal
✅ v0.3.5 — Anti-farming engine · Credential validators (email/phone/GitHub) · Biometric PROTOCOL constants
🚧 Phase 6 — Multi-country support (passport, DNI, CURP, RUT...)
🔮 Phase 7 — On-chain nullifier registry (optional, EVM-compatible)

______________________________________________________________________

阶段5f——SPT的自动更新（v0.3.6）✅

SPT（Soulprint协议令牌）现在自动续订，24小时令牌到期后不再停机。

运作原理

[Bot SDK] ──detects near-expiry──► POST /token/renew ──► [Validator Node]
                                        ↑ current SPT           ↓ fresh SPT (24h)
[Middleware] ◄─── X-Soulprint-Token-Renewed:  ─────────┘

续订窗口：

验证器端点

POST /token/renew
Body: { "spt": "" }

Response 200: {
  "spt": "",
  "expires_in": 86400,
  "renewed": true,
  "method": "preemptive" | "grace_window"
}

Express中间件（自动）

import { soulprint } from "soulprint-express";

app.use(soulprint({
  minScore: 40,
  nodeUrl: "https://validator.soulprint.digital",  // enables auto-renew
}));

// New token arrives in response header if renewed:
// X-Soulprint-Token-Renewed: 
// X-Soulprint-Expires-In: 86400

MCP中间件（自动）

import { requireSoulprint } from "soulprint-mcp";

server.use(requireSoulprint({
  minScore: 65,
  nodeUrl: "https://validator.soulprint.digital",
}));
// Renewed token propagated in context.meta["x-soulprint-token-renewed"]

手册（任何SDK）

import { autoRenew, needsRenewal } from "soulprint-core";

const check = needsRenewal(currentSpt);
if (check.needsRenew) {
  const { spt, renewed } = await autoRenew(currentSpt, { nodeUrl });
  if (renewed) saveSpt(spt);  // persist the new token
}

第5g阶段——挑战-响应对等完整性+snarkjs修复（v0.3.7）✅

关键错误修复-- soulprint-zkp@0.1.5

verifyProof() 从v0.1.0开始就被默默地打破了。snarkjs CJS模块具有 __esModule: true 但没有 .default 属性--TypeScript的 __importDefault 按原样返回模块，然后访问代码 .default.groth16 这是 undefined。所有ZK验证在运行时崩溃。

// ❌ Before (broken):
import snarkjs from "snarkjs";          // compiles to snarkjs_1.default.groth16 → undefined

// ✅ After (fixed):
import * as snarkjs from "snarkjs";     // compiles to snarkjs.groth16 ✅

挑战响应协议(soulprint-network@0.3.7)

对等方现在通过加密验证远程节点是否正在运行 未修改的ZK验证码 在将它们加入网络之前。

Challenger                          Peer
    │                                 │
    │── POST /challenge ─────────────►│
    │   {challenge_id, nonce,         │
    │    valid_proof,                 │  verifyProof(valid_proof)   → true
    │    invalid_proof}               │  verifyProof(invalid_proof) → false
    │                                 │  sign(results, node_key)
    │◄── {result_valid: true, ────────│
    │     result_invalid: false,      │
    │     signature: Ed25519(...)}    │
    │                                 │
    │  verify signature ✅            │
    │  result_valid == true ✅        │
    │  result_invalid == false ✅     │
    │                                 │
    │  → PEER ACCEPTED                │

阻止的攻击：

生成的证明无效 --挑战者用随机随机数对有效证明进行变异：

invalid_proof.pi_a[0] = (valid_proof.pi_a[0] + nonce) mod p

这产生了一个密码学上无效的证明，snarkjs总是会拒绝——但如果没有随机数，它是不可预测的。

自动对等验证 — POST /peers/register 现在运行 verifyPeerBehavior() 在接受任何同行之前。具有修改的ZK代码的对等体被HTTP 403拒绝。

第5h阶段——DPoP：证明持有（v0.3.8）✅

SPT代币是不记名代币——被盗代币可以使用到到期（24小时）。 磷酸二苯一辛酯 通过要求每个请求都有一个新的加密证明来关闭此窗口。

Without DPoP:  stolen SPT → attacker calls API → SUCCESS ✗
With DPoP:     stolen SPT → attacker has no private key → 401 ✓

它是如何工作的：

每个请求都携带 X-Soulprint-Proof --用用户的Ed25519私钥签名的有效载荷：

{
  typ:      "soulprint-dpop",
  method:   "POST",           // HTTP method — bound
  url:      "https://...",    // exact URL — bound
  nonce:    "a3f1b2...",      // 16 random bytes — unique per request
  iat:      1740000000,       // expires in 5 minutes
  spt_hash: sha256(spt),      // bound to THIS specific token
}
// Signed: Ed25519(sha256(JSON.stringify(payload)), privateKey)

已阻止的攻击（8）： 令牌盗窃、重放、URL MITM、方法MITM、DID不匹配、过期证明、格式错误证明、外来令牌重用。

API

import { signDPoP, verifyDPoP, serializeDPoP, NonceStore } from "soulprint-core";

const proof  = signDPoP(privateKey, did, "POST", url, spt);
const header = serializeDPoP(proof);  // base64url string → X-Soulprint-Proof

const result = verifyDPoP(header, spt, "POST", url, nonceStore, sptDid);
// result.valid → bool | result.reason → string

______________________________________________________________________

第5i阶段——MCPRegistry：已验证的MCP生态系统（v0.3.9）✅

已验证MCP服务器的公共链上注册表。代理可以在信任服务器之前检查服务器是否合法。

合同： MCPRegistry.sol 在基础Sepolia\ 地址： 0x59EA3c8f60ecbAe22B4c323A8dDc2b0BCd9D3C2a\ 管理员： 灵魂印记协议（不是任何单独的MCP）

Unverified MCP:  agent connects → no guarantee → risk ✗
Verified MCP:    isVerified(0x...) → true on-chain → trusted ✓

注册流程：

# 1. Any dev registers their MCP (permissionless)
curl -X POST http://soulprint-node/admin/mcp/register \
  -d '{ "ownerKey": "0x...", "address": "0x...",
        "name": "My Finance MCP", "url": "https://...", "category": "finance" }'

# 2. Soulprint admin reviews and verifies
curl -X POST http://soulprint-node/admin/mcp/verify \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -d '{ "address": "0x..." }'
# → on-chain tx → MCPVerified event → permanent record

# 3. Anyone checks
curl http://soulprint-node/mcps/verified
# → [{ name: "My Finance MCP", badge: "✅ VERIFIED", verified_at: "..." }]

从代码检查：

import { isVerifiedOnChain, getMCPEntry } from "soulprint-network";

const trusted = await isVerifiedOnChain("0x...");  // → true/false, on-chain

const entry = await getMCPEntry("0x...");
// → { name, url, category, verified, verified_at, badge: "✅ VERIFIED by Soulprint" }

建筑分隔：

Soulprint validator = protocol authority → admin endpoints (verify/revoke)
Individual MCPs     = participants → read-only (check status, list verified)
MCPRegistry.sol     = source of truth → on-chain, immutable, auditable

______________________________________________________________________

第5j阶段——协议阈值：可变链上治理（v0.4.1）✅

协议阈值（SCORE_FOOR、VERIFIED_SCORE_FLOOR、FACE_SIM\_\*等）现在位于链上 ProtocolThresholds.sol 而不是硬编码。

合同（基础Sepolia）： 0xD8f78d65b35806101672A49801b57F743f2D2ab1

// Anyone can read
getThreshold("SCORE_FLOOR")         // → 65
getThreshold("FACE_SIM_DOC_SELFIE") // → 350 (= 0.35)
getAll()                            // → all 9 thresholds

// Only superAdmin can write
setThreshold("SCORE_FLOOR", 70)     // emits ThresholdUpdated event

// Admin transfer (2-step safety)
proposeSuperAdmin(addr) → acceptSuperAdmin()

验证器集成：

• 节点在启动时从区块链加载阈值（非阻塞，如果RPC无法访问，则回退到本地）
• 每10分钟自动刷新一次
• 新端点： GET /protocol/thresholds

{
  "source": "blockchain",
  "contract": "0xD8f78d65b35806101672A49801b57F743f2D2ab1",
  "thresholds": {
    "SCORE_FLOOR": 65,
    "VERIFIED_SCORE_FLOOR": 52,
    "MIN_ATTESTER_SCORE": 65,
    "FACE_SIM_DOC_SELFIE": 0.35,
    "FACE_SIM_SELFIE_SELFIE": 0.65,
    "DEFAULT_REPUTATION": 10,
    "IDENTITY_MAX": 80,
    "REPUTATION_MAX": 20
  }
}

测验： 在Base Sepolia进行17/17实际流量测试(tests/protocol-thresholds-tests.mjs)

______________________________________________________________________

协议规范

看 规格/SIP-v0.1.md 用于Soulprint身份协议规范。

______________________________________________________________________

贡献

看 贡献.md。欢迎所有国家/地区加入您的身份证件格式 packages/verify-local/src/document/.

______________________________________________________________________

许可证

麻省理工学院——个人和商业用途免费。

______________________________________________________________________

*专为人工智能时代打造。每个机器人背后都有一个灵魂。*