Proof-of-Play infrastructure, built for TypeScript.

Installation

Install the Community SDK with npm. Node.js 20 or newer is supported. Browser builds must never include API keys, OpenAI credentials, wallet material, or signing secrets.

npm i @btdworks/sdk

Five-minute quick start

This complete path starts a session, defines a typed achievement, captures evidence, verifies it, and issues a credential.

import {
  BtdClient,
  MemoryStorage,
  MockTransport,
  achievement,
  event,
} from "@btdworks/sdk";

type GameEvents = {
  enemy_defeated: {
    enemyId: string;
    critical: boolean;
  };
};

const btd = new BtdClient<GameEvents>({
  gameId: "arena-legends",
  environment: "development",
  storage: new MemoryStorage(),
  transport: new MockTransport(),
});

const session = await btd.sessions.start({ playerId: "player_123" });

btd.achievements.register(
  achievement("boss-breaker")
    .named("Boss Breaker")
    .when(
      event("enemy_defeated")
        .where("enemyId", "equals", "boss_01")
        .and("critical", "equals", true),
    )
    .build(),
);

await btd.capture("enemy_defeated", {
  enemyId: "boss_01",
  critical: true,
});

const result = await btd.verify("boss-breaker", {
  playerId: "player_123",
  sessionId: session.sessionId,
});

if (result.verified) {
  const credential = await btd.credentials.issue(result);
  console.log(credential);
}

Core concepts

Typed gameplay events

The event map is the integration contract between your game and the SDK. Event names become literal types, while each name receives its own payload schema at compile time.

type ArenaEvents = {
  match_started: { mode: "ranked" | "casual"; mapId: string };
  enemy_defeated: {
    enemyId: string;
    weapon: string;
    damage: number;
    critical: boolean;
  };
  match_completed: {
    score: number;
    placement: number;
    durationMs: number;
  };
};

const btd = new BtdClient<ArenaEvents>({
  gameId: "arena-legends",
  environment: "development",
});

Runtime validation protects the event envelope, while application-level Zod schemas should validate payloads that originate outside trusted game code. Duplicate IDs, sequence regressions, unsafe property paths, oversized payloads, and closed sessions are rejected.

Achievement rules

Rules are plain JSON data. They can be reviewed in source control, stored in a trusted configuration service, and versioned independently from SDK releases.

const flawlessRun = achievement("flawless-run")
  .named("Flawless Run")
  .versioned(1)
  .when(
    and(
      event("enemy_defeated")
        .where("critical", "equals", true)
        .build(),
      count("enemy_defeated", "gte", 10),
      sequence(
        ["match_started", "enemy_defeated", "match_completed"],
        15 * 60_000,
      ),
    ),
  )
  .within(30 * 60_000)
  .build();

Verification

Verification evaluates deterministic rules against normalized evidence. A failed result remains useful: it includes stable reason codes, matched event IDs, individual branch results, confidence, and a canonical SHA-256 evidence digest.

Portable credentials

Credential issuing rejects unverified results. The resulting JSON is inspired by verifiable credential data models without claiming full W3C VC conformance. It includes issuer, subject, game, achievement, evidence digest, timestamps, and a digest or injected signature proof.

Optional OpenAI interpretation

Optional Solana publishing

Import Solana support from @btdworks/sdk/solana. The proof builder canonicalizes and hashes a credential, while the injected adapter owns transaction construction, signing, submission, and confirmation.

Storage and transport adapters

Use MemoryStorage for tests and offline Node environments, LocalStorageAdapter for guarded browser persistence, HttpTransport for remote services, and MockTransport for deterministic examples. Custom adapters keep the SDK independent from databases and frameworks.

Configuration reference

Errors and observability

Catch BtdError and branch on stable codes such as INVALID_EVENT, DUPLICATE_EVENT, SESSION_CLOSED, VERIFICATION_FAILED, INTERPRETATION_FAILED, and SOLANA_PUBLISH_FAILED. Lifecycle subscriptions expose capture, verification, credential, and publication progress without allowing listener failures to interrupt SDK operations.

Security and trust boundaries

Roadmap

Planned capabilities are directional and do not have promised dates.

• Unity package and editor tooling
• Unreal Engine plugin
• Godot addon
• Hosted rule dashboard
• Managed verification
• Batch and streaming ingestion
• Anti-cheat and anomaly signals
• Cross-game reputation
• Credential revocation
• Solana compressed credentials
• Webhooks and realtime subscriptions
• Analytics and gameplay funnels

Changelog