sdk

@bolyra/sdk

TypeScript SDK for Bolyra — mutual ZKP authentication for humans and AI agents.

New here? Start with the 5-minute Quickstart — from npm install to on-chain verification.

Install

npm install @bolyra/sdk

Quick Start

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);

Low-level primitives (v0.6.0+)

For advanced use — e.g. building an external verifier or recomputing credential/scope commitments — the SDK exports its Poseidon hashes and BabyJubjub EdDSA primitives:

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 returns false (never throws) on malformed input. See @bolyra/cli's bolyra verify for a full external-verifier reference.

Permissions

Permissions use cumulative bit encoding — higher tiers imply lower ones:

Bit	Permission	Notes
0	READ_DATA
1	WRITE_DATA
2	FINANCIAL_SMALL	< $100
3	FINANCIAL_MEDIUM	< $10,000 (implies bit 2)
4	FINANCIAL_UNLIMITED	Unlimited (implies 2+3)
5	SIGN_ON_BEHALF
6	SUB_DELEGATE
7	ACCESS_PII

API Status

Function	Status
createHumanIdentity()	v0.1
createAgentCredential()	v0.1
permissionsToBitmask()	v0.1
validateCumulativeBitEncoding()	v0.1
proveHandshake()	v0.2
verifyHandshake()	v0.2
delegate()	v0.3
verifyDelegation()	v0.3

License

Apache-2.0 — see LICENSE.