@whitewall-os/sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,200 @@
+import { createPublicClient, http, zeroAddress, } from "viem";
+import { baseSepolia } from "viem/chains";
+import { humanVerifiedPolicyAbi, identityRegistryAbi, validationRegistryAbi, whitewallConsumerAbi, } from "./abis.js";
+import { addresses } from "./addresses.js";
+const HUMAN_VERIFIED_TAG = "HUMAN_VERIFIED";
+const chainMap = {
+    baseSepolia,
+};
+export class WhitewallOS {
+    client;
+    addrs;
+    policy = null;
+    constructor(client, addrs) {
+        this.client = client;
+        this.addrs = addrs;
+    }
+    /**
+     * Create and connect a WhitewallOS instance.
+     * Reads policy config from on-chain HumanVerifiedPolicy contract.
+     */
+    static async connect(config) {
+        const addrs = addresses[config.chain];
+        const client = config.publicClient ??
+            createPublicClient({
+                chain: chainMap[config.chain],
+                transport: http(config.rpcUrl),
+            });
+        const instance = new WhitewallOS(client, addrs);
+        await instance.loadPolicyConfig();
+        return instance;
+    }
+    /** Read policy configuration from the on-chain HumanVerifiedPolicy contract */
+    async loadPolicyConfig() {
+        const [identityRegistry, validationRegistry, worldIdValidator, requiredTier] = await Promise.all([
+            this.client.readContract({
+                address: this.addrs.humanVerifiedPolicy,
+                abi: humanVerifiedPolicyAbi,
+                functionName: "getIdentityRegistry",
+            }),
+            this.client.readContract({
+                address: this.addrs.humanVerifiedPolicy,
+                abi: humanVerifiedPolicyAbi,
+                functionName: "getValidationRegistry",
+            }),
+            this.client.readContract({
+                address: this.addrs.humanVerifiedPolicy,
+                abi: humanVerifiedPolicyAbi,
+                functionName: "getWorldIdValidator",
+            }),
+            this.client.readContract({
+                address: this.addrs.humanVerifiedPolicy,
+                abi: humanVerifiedPolicyAbi,
+                functionName: "getRequiredTier",
+            }),
+        ]);
+        this.policy = { identityRegistry, validationRegistry, worldIdValidator, requiredTier };
+    }
+    get policyConfig() {
+        if (!this.policy)
+            throw new Error("WhitewallOS not connected. Use WhitewallOS.connect()");
+        return this.policy;
+    }
+    // ─── Core Read Methods ───
+    async isRegistered(agentId) {
+        try {
+            const owner = await this.client.readContract({
+                address: this.policyConfig.identityRegistry,
+                abi: identityRegistryAbi,
+                functionName: "ownerOf",
+                args: [agentId],
+            });
+            return owner !== zeroAddress;
+        }
+        catch {
+            return false;
+        }
+    }
+    async isHumanVerified(agentId) {
+        const summary = await this.getValidationSummary(agentId);
+        return summary.count > 0n && summary.avgScore >= this.policyConfig.requiredTier;
+    }
+    async getOwner(agentId) {
+        return this.client.readContract({
+            address: this.policyConfig.identityRegistry,
+            abi: identityRegistryAbi,
+            functionName: "ownerOf",
+            args: [agentId],
+        });
+    }
+    async getAgentWallet(agentId) {
+        return this.client.readContract({
+            address: this.policyConfig.identityRegistry,
+            abi: identityRegistryAbi,
+            functionName: "getAgentWallet",
+            args: [agentId],
+        });
+    }
+    async getTokenURI(agentId) {
+        return this.client.readContract({
+            address: this.policyConfig.identityRegistry,
+            abi: identityRegistryAbi,
+            functionName: "tokenURI",
+            args: [agentId],
+        });
+    }
+    async getMetadata(agentId, key) {
+        return this.client.readContract({
+            address: this.policyConfig.identityRegistry,
+            abi: identityRegistryAbi,
+            functionName: "getMetadata",
+            args: [agentId, key],
+        });
+    }
+    // ─── Validation ───
+    async getValidationSummary(agentId) {
+        const [count, avgResponse] = await this.client.readContract({
+            address: this.policyConfig.validationRegistry,
+            abi: validationRegistryAbi,
+            functionName: "getSummary",
+            args: [agentId, [this.policyConfig.worldIdValidator], HUMAN_VERIFIED_TAG],
+        });
+        return { count: BigInt(count), avgScore: avgResponse };
+    }
+    async getAgentValidations(agentId) {
+        return this.client.readContract({
+            address: this.policyConfig.validationRegistry,
+            abi: validationRegistryAbi,
+            functionName: "getAgentValidations",
+            args: [agentId],
+        });
+    }
+    // ─── Composite: Full Status ───
+    async getAgentStatus(agentId) {
+        const registered = await this.isRegistered(agentId);
+        if (!registered) {
+            return {
+                isRegistered: false,
+                isHumanVerified: false,
+                tier: 0,
+                owner: zeroAddress,
+                agentWallet: zeroAddress,
+                validationCount: 0n,
+            };
+        }
+        const [owner, agentWallet, summary] = await Promise.all([
+            this.getOwner(agentId),
+            this.getAgentWallet(agentId),
+            this.getValidationSummary(agentId),
+        ]);
+        const isHumanVerified = summary.count > 0n && summary.avgScore >= this.policyConfig.requiredTier;
+        const tier = isHumanVerified ? this.policyConfig.requiredTier : 1;
+        return {
+            isRegistered: true,
+            isHumanVerified,
+            tier,
+            owner,
+            agentWallet,
+            validationCount: summary.count,
+        };
+    }
+    // ─── Event Watching ───
+    onAccessGranted(callback) {
+        return this.client.watchEvent({
+            address: this.addrs.whitewallConsumer,
+            event: whitewallConsumerAbi[0], // AccessGranted
+            onLogs: (logs) => {
+                for (const log of logs) {
+                    callback({
+                        agentId: log.args.agentId,
+                        accountableHuman: log.args.accountableHuman,
+                        tier: Number(log.args.tier),
+                        blockNumber: log.blockNumber,
+                        transactionHash: log.transactionHash,
+                    });
+                }
+            },
+        });
+    }
+    onRegistered(callback) {
+        return this.client.watchEvent({
+            address: this.policyConfig.identityRegistry,
+            event: identityRegistryAbi[5], // Registered event
+            onLogs: (logs) => {
+                for (const log of logs) {
+                    callback(log.args.agentId, log.args.owner);
+                }
+            },
+        });
+    }
+    // ─── Utilities ───
+    getAddresses() {
+        return this.addrs;
+    }
+    getPolicyConfig() {
+        return this.policyConfig;
+    }
+    getPublicClient() {
+        return this.client;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { WhitewallOS } from "./client.js";
+export type { WhitewallOSConfig } from "./client.js";
+export type { AgentStatus, AccessGrantedEvent, ValidationSummary } from "./types.js";
+export type { ChainName, WhitewallOSAddresses, PolicyConfig } from "./addresses.js";
+export { addresses } from "./addresses.js";
+export { humanVerifiedPolicyAbi, identityRegistryAbi, validationRegistryAbi, whitewallConsumerAbi, worldIdValidatorAbi, } from "./abis.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { WhitewallOS } from "./client.js";
+export { addresses } from "./addresses.js";
+export { humanVerifiedPolicyAbi, identityRegistryAbi, validationRegistryAbi, whitewallConsumerAbi, worldIdValidatorAbi, } from "./abis.js";

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import type { Address } from "viem";
+export interface AgentStatus {
+    isRegistered: boolean;
+    isHumanVerified: boolean;
+    tier: number;
+    owner: Address;
+    agentWallet: Address;
+    validationCount: bigint;
+}
+export interface AccessGrantedEvent {
+    agentId: bigint;
+    accountableHuman: Address;
+    tier: number;
+    blockNumber: bigint;
+    transactionHash: `0x${string}`;
+}
+export interface ValidationSummary {
+    count: bigint;
+    avgScore: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@whitewall-os/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Whitewall OS — AI agent accountability protocol",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit.test.ts",
+    "test:integration": "vitest run test/integration.test.ts"
+  },
+  "dependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "MIT"
+}

package/src/abis.ts

@@ -0,0 +1,218 @@
+// ── HumanVerifiedPolicy — entry point, SDK reads config from here ──
+
+export const humanVerifiedPolicyAbi = [
+  {
+    inputs: [],
+    name: "getRequiredTier",
+    outputs: [{ name: "", type: "uint8" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "getIdentityRegistry",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "getValidationRegistry",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [],
+    name: "getWorldIdValidator",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+] as const;
+
+// ── IdentityRegistry ──
+
+export const identityRegistryAbi = [
+  {
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    name: "ownerOf",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "agentId", type: "uint256" }],
+    name: "getAgentWallet",
+    outputs: [{ name: "", type: "address" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "owner", type: "address" }],
+    name: "balanceOf",
+    outputs: [{ name: "", type: "uint256" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    name: "tokenURI",
+    outputs: [{ name: "", type: "string" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "metadataKey", type: "string" },
+    ],
+    name: "getMetadata",
+    outputs: [{ name: "", type: "bytes" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "agentId", type: "uint256" },
+      { indexed: false, name: "agentURI", type: "string" },
+      { indexed: true, name: "owner", type: "address" },
+    ],
+    name: "Registered",
+    type: "event",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "from", type: "address" },
+      { indexed: true, name: "to", type: "address" },
+      { indexed: true, name: "tokenId", type: "uint256" },
+    ],
+    name: "Transfer",
+    type: "event",
+  },
+  {
+    inputs: [{ name: "agentURI", type: "string" }],
+    name: "register",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+  {
+    inputs: [
+      { name: "validator", type: "address" },
+      { name: "agentId", type: "uint256" },
+    ],
+    name: "approve",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+] as const;
+
+// ── ValidationRegistry ──
+
+export const validationRegistryAbi = [
+  {
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "validatorAddresses", type: "address[]" },
+      { name: "tag", type: "string" },
+    ],
+    name: "getSummary",
+    outputs: [
+      { name: "count", type: "uint64" },
+      { name: "avgResponse", type: "uint8" },
+    ],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "agentId", type: "uint256" }],
+    name: "getAgentValidations",
+    outputs: [{ name: "", type: "bytes32[]" }],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    inputs: [{ name: "requestHash", type: "bytes32" }],
+    name: "getValidationStatus",
+    outputs: [
+      { name: "validatorAddress", type: "address" },
+      { name: "agentId", type: "uint256" },
+      { name: "response", type: "uint8" },
+      { name: "responseHash", type: "bytes32" },
+      { name: "tag", type: "string" },
+      { name: "lastUpdate", type: "uint256" },
+    ],
+    stateMutability: "view",
+    type: "function",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "validatorAddress", type: "address" },
+      { indexed: true, name: "agentId", type: "uint256" },
+      { indexed: false, name: "requestURI", type: "string" },
+      { indexed: true, name: "requestHash", type: "bytes32" },
+    ],
+    name: "ValidationRequest",
+    type: "event",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "validatorAddress", type: "address" },
+      { indexed: true, name: "agentId", type: "uint256" },
+      { indexed: true, name: "requestHash", type: "bytes32" },
+      { indexed: false, name: "response", type: "uint8" },
+      { indexed: false, name: "responseURI", type: "string" },
+      { indexed: false, name: "responseHash", type: "bytes32" },
+      { indexed: false, name: "tag", type: "string" },
+    ],
+    name: "ValidationResponse",
+    type: "event",
+  },
+] as const;
+
+// ── WorldIDValidator ──
+
+export const worldIdValidatorAbi = [
+  {
+    inputs: [
+      { name: "agentId", type: "uint256" },
+      { name: "root", type: "uint256" },
+      { name: "nullifierHash", type: "uint256" },
+      { name: "proof", type: "uint256[8]" },
+    ],
+    name: "verifyAndSetHumanTag",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function",
+  },
+] as const;
+
+// ── WhitewallConsumer ──
+
+export const whitewallConsumerAbi = [
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "agentId", type: "uint256" },
+      { indexed: true, name: "accountableHuman", type: "address" },
+      { indexed: false, name: "tier", type: "uint8" },
+    ],
+    name: "AccessGranted",
+    type: "event",
+  },
+  {
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "agentId", type: "uint256" },
+      { indexed: false, name: "reason", type: "bytes32" },
+    ],
+    name: "AccessDenied",
+    type: "event",
+  },
+] as const;

package/src/addresses.ts

@@ -0,0 +1,23 @@
+import type { Address } from "viem";
+
+export type ChainName = "baseSepolia";
+
+export interface WhitewallOSAddresses {
+  humanVerifiedPolicy: Address;
+  whitewallConsumer: Address;
+}
+
+/** Protocol-level policy config, read from on-chain HumanVerifiedPolicy */
+export interface PolicyConfig {
+  identityRegistry: Address;
+  validationRegistry: Address;
+  worldIdValidator: Address;
+  requiredTier: number;
+}
+
+export const addresses: Record<ChainName, WhitewallOSAddresses> = {
+  baseSepolia: {
+    humanVerifiedPolicy: "0x8f66f55f4ade4e64b105820972d444a56449e8b3",
+    whitewallConsumer: "0xec3114ea6bb29f77b63cd1223533870b663120bb",
+  },
+} as const;