sdk

@bolyra/sdk

Bolyra 用の TypeScript SDK — 人間と AI エージェントのための相互 ZKP 認証です。

初めての方へ。 npm install からオンチェーン検証までを説明する5分間のクイックスタートから始めてください。

インストール

npm install @bolyra/sdk

クイックスタート

import {
  createHumanIdentity,
  createAgentCredential,
  Permission,
  proveHandshake,
  verifyHandshake,
} from '@bolyra/sdk';

// 1. Create identities
const human = await createHumanIdentity(123456789n);
const agent = await createAgentCredential(
  12345n,
  operatorPrivateKey,
  [Permission.READ_DATA, Permission.WRITE_DATA],
  BigInt(Math.floor(Date.now() / 1000) + 86400),
);

// 2. Generate mutual handshake proofs (parallel, ~16s)
const { humanProof, agentProof, nonce } = await proveHandshake(human, agent);

// 3. Verify locally
const result = await verifyHandshake(humanProof, agentProof, nonce);
console.log('Verified:', result.verified); // true
console.log('Human nullifier:', result.humanNullifier);
console.log('Agent scope commitment:', result.scopeCommitment);

// 4. Submit to chain (via ethers.js)
// await registry.verifyHandshake(humanProof, agentProof, nonce);

低レベルプリミティブ（v0.6.0+）

高度な用途（外部検証器の構築や、クレデンシャル／スコープのコミットメントの再計算など）向けに、この SDK は Poseidon ハッシュと BabyJubjub EdDSA プリミティブをエクスポートします。

import { poseidon5, eddsaSign, eddsaVerify, derivePublicKey } from '@bolyra/sdk';

const pub = await derivePublicKey(operatorPrivateKey);   // { x, y }
const sig = await eddsaSign(operatorPrivateKey, message); // { R8: { x, y }, S }
const ok  = await eddsaVerify(pub, message, sig);         // boolean
const h   = await poseidon5(a, b, c, d, e);               // bigint

eddsaVerify は、不正な形式の入力に対して例外をスローせず、false を返します。外部検証器の完全なリファレンスについては、@bolyra/cli の bolyra verify を参照してください。

権限

権限には累積ビットエンコーディングを使用します。上位の権限には下位の権限が含まれます。

ビット	権限	備考
0	READ_DATA
1	WRITE_DATA
2	FINANCIAL_SMALL	< $100
3	FINANCIAL_MEDIUM	< $10,000（ビット 2 を含む）
4	FINANCIAL_UNLIMITED	無制限（ビット 2、3 を含む）
5	SIGN_ON_BEHALF
6	SUB_DELEGATE
7	ACCESS_PII

API のステータス

関数	ステータス
createHumanIdentity()	v0.1
createAgentCredential()	v0.1
permissionsToBitmask()	v0.1
validateCumulativeBitEncoding()	v0.1
proveHandshake()	v0.2
verifyHandshake()	v0.2
delegate()	v0.3
verifyDelegation()	v0.3

ライセンス

Apache-2.0 — LICENSE を参照してください。