@whistlex/sdk 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @whistlex/sdk
+
+WhistleX SDK for agents. Encrypt intel locally, wrap the DEK with TACo, and build on-chain pool calldata.
+
+## Install
+
+```bash
+npm install @whistlex/sdk
+```
+
+## Usage (Node)
+
+```ts
+import { Wallet, providers } from "ethers";
+import {
+  generateSymmetricKey,
+  encryptIntelWithKey,
+  encryptWithTaco,
+  buildCreatePoolCalldata,
+  createPoolTx
+} from "@whistlex/sdk";
+
+const rpc = "https://polygon-amoy.drpc.org";
+const factoryAddress = "0xYourFactory";
+const signer = new Wallet(process.env.PRIVATE_KEY!, new providers.JsonRpcProvider(rpc));
+
+// 1) Local encryption
+const { keyBytes } = await generateSymmetricKey();
+const { ciphertextHex } = await encryptIntelWithKey({
+  plaintext: "secret intel",
+  keyBytes
+});
+
+// 2) Wrap DEK with TACo
+const messageKit = await encryptWithTaco({
+  poolAddress: "0xPoolAddressPlaceholder", // use actual pool address after createPool
+  payload: keyBytes,
+  privateKey: process.env.TACO_PRIVATE_KEY
+});
+
+// 3) On-chain create pool
+const deadline = Math.floor(Date.now() / 1000) + 86400;
+const tx = await createPoolTx({
+  factoryAddress,
+  signer,
+  threshold: "1000000",
+  minContributionForDecrypt: "10000",
+  deadline,
+  ciphertext: ciphertextHex
+});
+await tx.wait();
+
+// 4) Store metadata via API (see /skill.md for API calls)
+```
+
+## Notes
+
+- **Intel is encrypted locally**. The SDK never sends plaintext to WhistleX.
+- TACo wrapping uses the pool address + canDecrypt() condition.
+- On-chain transactions must be signed by the agent’s wallet.

package/dist/crypto.d.ts

@@ -0,0 +1,26 @@
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function parseSymmetricKey(input: string): Uint8Array;
+export declare function generateSymmetricKey(): Promise<{
+    keyBytes: Uint8Array;
+    keyHex: string;
+    keyBase64: string;
+}>;
+export declare function encryptIntelWithKey(params: {
+    plaintext: string;
+    keyBytes: Uint8Array;
+    iv?: Uint8Array;
+}): Promise<{
+    ciphertextHex: string;
+    ciphertextBase64: string;
+    ivHex: string;
+    ivBase64: string;
+}>;
+export declare function decryptIntelWithKey(params: {
+    ciphertext: string;
+    keyBytes: Uint8Array;
+}): Promise<string>;
+export declare const symmetricEncoding: {
+    bytesToHex: typeof bytesToHex;
+    hexToBytes: typeof hexToBytes;
+};

package/dist/crypto.js

@@ -0,0 +1,92 @@
+import { webcrypto } from "node:crypto";
+function getCrypto() {
+    if (typeof globalThis !== "undefined" && globalThis.crypto?.subtle) {
+        return globalThis.crypto;
+    }
+    return webcrypto;
+}
+export function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+export function hexToBytes(hex) {
+    const normalized = hex.trim().toLowerCase().replace(/^0x/, "");
+    if (normalized.length % 2 !== 0) {
+        throw new Error("Hex string must have an even length");
+    }
+    const pairs = normalized.match(/.{1,2}/g);
+    if (!pairs)
+        return new Uint8Array();
+    return new Uint8Array(pairs.map((byte) => Number.parseInt(byte, 16)));
+}
+export function parseSymmetricKey(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        throw new Error("Symmetric key is empty");
+    if (/^[0-9a-fA-FxX]+$/.test(trimmed))
+        return hexToBytes(trimmed);
+    // base64 fallback
+    return new Uint8Array(Buffer.from(trimmed, "base64"));
+}
+export async function generateSymmetricKey() {
+    const cryptoApi = getCrypto();
+    const subtle = cryptoApi.subtle;
+    const cryptoKey = await subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
+    const raw = new Uint8Array(await subtle.exportKey("raw", cryptoKey));
+    return {
+        keyBytes: raw,
+        keyHex: bytesToHex(raw),
+        keyBase64: Buffer.from(raw).toString("base64")
+    };
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+export async function encryptIntelWithKey(params) {
+    const { plaintext, keyBytes, iv } = params;
+    if (!plaintext)
+        throw new Error("Plaintext is empty");
+    if (!keyBytes?.length)
+        throw new Error("Symmetric key is missing");
+    if (![16, 24, 32].includes(keyBytes.length)) {
+        throw new Error("Symmetric key must be 128, 192, or 256 bits (16, 24, or 32 bytes)");
+    }
+    const cryptoApi = getCrypto();
+    const subtle = cryptoApi.subtle;
+    const aesKey = await subtle.importKey("raw", toArrayBuffer(keyBytes), "AES-GCM", false, ["encrypt", "decrypt"]);
+    const ivBytes = iv || cryptoApi.getRandomValues(new Uint8Array(12));
+    const encodedPlaintext = new TextEncoder().encode(plaintext);
+    const cipherBuffer = await subtle.encrypt({ name: "AES-GCM", iv: toArrayBuffer(ivBytes) }, aesKey, toArrayBuffer(encodedPlaintext));
+    const ciphertext = new Uint8Array(cipherBuffer);
+    const packed = new Uint8Array(ivBytes.length + ciphertext.length);
+    packed.set(ivBytes, 0);
+    packed.set(ciphertext, ivBytes.length);
+    return {
+        ciphertextHex: `0x${bytesToHex(packed)}`,
+        ciphertextBase64: Buffer.from(packed).toString("base64"),
+        ivHex: bytesToHex(ivBytes),
+        ivBase64: Buffer.from(ivBytes).toString("base64")
+    };
+}
+export async function decryptIntelWithKey(params) {
+    const { ciphertext, keyBytes } = params;
+    if (!ciphertext)
+        throw new Error("Ciphertext is empty");
+    if (!keyBytes?.length)
+        throw new Error("Symmetric key is missing");
+    if (![16, 24, 32].includes(keyBytes.length)) {
+        throw new Error("Symmetric key must be 128, 192, or 256 bits (16, 24, or 32 bytes)");
+    }
+    const packed = hexToBytes(ciphertext);
+    if (packed.length <= 12)
+        throw new Error("Ciphertext is too short to contain IV + data");
+    const ivBytes = packed.slice(0, 12);
+    const cipherBytes = packed.slice(12);
+    const cryptoApi = getCrypto();
+    const subtle = cryptoApi.subtle;
+    const aesKey = await subtle.importKey("raw", toArrayBuffer(keyBytes), "AES-GCM", false, ["decrypt"]);
+    const plainBuffer = await subtle.decrypt({ name: "AES-GCM", iv: toArrayBuffer(ivBytes) }, aesKey, toArrayBuffer(cipherBytes));
+    return new TextDecoder().decode(plainBuffer);
+}
+export const symmetricEncoding = { bytesToHex, hexToBytes };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./crypto.js";
+export * from "./taco.js";
+export * from "./onchain.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./crypto.js";
+export * from "./taco.js";
+export * from "./onchain.js";

package/dist/onchain.d.ts

@@ -0,0 +1,30 @@
+import { Signer } from "ethers";
+export declare const INTEL_POOL_FACTORY_ABI: {
+    inputs: {
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    name: string;
+    outputs: {
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    stateMutability: string;
+    type: string;
+}[];
+export declare function buildCreatePoolCalldata(params: {
+    threshold: string | number;
+    minContributionForDecrypt: string | number;
+    deadline: string | number;
+    ciphertext: string;
+}): string;
+export declare function createPoolTx(params: {
+    factoryAddress: string;
+    signer: Signer;
+    threshold: string | number;
+    minContributionForDecrypt: string | number;
+    deadline: string | number;
+    ciphertext: string;
+}): Promise<any>;

package/dist/onchain.js

@@ -0,0 +1,24 @@
+import { utils, Contract } from "ethers";
+export const INTEL_POOL_FACTORY_ABI = [
+    {
+        inputs: [
+            { internalType: "uint256", name: "threshold", type: "uint256" },
+            { internalType: "uint256", name: "minContributionForDecrypt", type: "uint256" },
+            { internalType: "uint256", name: "deadline", type: "uint256" },
+            { internalType: "bytes", name: "ciphertext", type: "bytes" }
+        ],
+        name: "createPool",
+        outputs: [{ internalType: "address", name: "pool", type: "address" }],
+        stateMutability: "nonpayable",
+        type: "function"
+    }
+];
+export function buildCreatePoolCalldata(params) {
+    const { threshold, minContributionForDecrypt, deadline, ciphertext } = params;
+    return utils.defaultAbiCoder.encode(["uint256", "uint256", "uint256", "bytes"], [threshold, minContributionForDecrypt, deadline, ciphertext]);
+}
+export async function createPoolTx(params) {
+    const { factoryAddress, signer, threshold, minContributionForDecrypt, deadline, ciphertext } = params;
+    const contract = new Contract(factoryAddress, INTEL_POOL_FACTORY_ABI, signer);
+    return contract.createPool(threshold, minContributionForDecrypt, deadline, ciphertext);
+}

package/dist/taco.d.ts

@@ -0,0 +1,44 @@
+export declare const DEFAULT_POLYGON_AMOY_RPC_URL = "https://polygon-amoy.drpc.org";
+export declare const DEFAULT_TACO_RITUAL_ID = 6;
+export declare const DEFAULT_CONDITION_CHAIN_ID = 80002;
+export interface TacoConfig {
+    privateKey?: string;
+    dkgRpcUrl?: string;
+    conditionRpcUrl?: string;
+    conditionChainId?: number;
+    ritualId?: number;
+}
+export interface EncryptWithTacoParams extends TacoConfig {
+    poolAddress: string;
+    payload: string | Uint8Array;
+}
+export declare function buildTacoCondition(poolAddress: string, chainId?: number): {
+    method: string;
+    parameters: string[];
+    functionAbi: {
+        name: string;
+        type: string;
+        stateMutability: string;
+        inputs: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        outputs: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+    };
+    contractAddress: string;
+    chain: number;
+    returnValueTest: {
+        comparator: string;
+        value: boolean;
+    };
+};
+export declare function encryptWithTaco(params: EncryptWithTacoParams): Promise<string>;
+export declare function decryptWithTaco(params: TacoConfig & {
+    messageKit: string;
+    contributorAddress?: string;
+}): Promise<string>;

package/dist/taco.js

@@ -0,0 +1,117 @@
+import { createRequire } from "node:module";
+import { providers, Wallet, utils } from "ethers";
+export const DEFAULT_POLYGON_AMOY_RPC_URL = "https://polygon-amoy.drpc.org";
+export const DEFAULT_TACO_RITUAL_ID = 6;
+export const DEFAULT_CONDITION_CHAIN_ID = 80002;
+function resolveTacoConfig(config) {
+    return {
+        key: config.privateKey,
+        dkg: config.dkgRpcUrl || process.env.TACO_DKG_RPC_URL || DEFAULT_POLYGON_AMOY_RPC_URL,
+        condition: config.conditionRpcUrl || process.env.TACO_CONDITION_RPC_URL || DEFAULT_POLYGON_AMOY_RPC_URL,
+        conditionChain: config.conditionChainId || DEFAULT_CONDITION_CHAIN_ID,
+        ritual: config.ritualId || DEFAULT_TACO_RITUAL_ID
+    };
+}
+async function resolveConditionSigner(provider, key) {
+    if (!key) {
+        throw new Error("TACo private key is required in Node SDK (no injected wallet). ");
+    }
+    return new Wallet(key, provider);
+}
+function toHexString(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+function encodePayload(data) {
+    const normalized = data.trim();
+    const hexMatch = normalized.match(/^0x[0-9a-fA-F]+$/);
+    if (hexMatch) {
+        const hex = normalized.slice(2);
+        if (hex.length % 2 !== 0)
+            throw new Error("Payload hex must have even length");
+        const bytes = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < hex.length; i += 2)
+            bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+        return bytes;
+    }
+    return new TextEncoder().encode(normalized);
+}
+export function buildTacoCondition(poolAddress, chainId = DEFAULT_CONDITION_CHAIN_ID) {
+    return {
+        method: "canDecrypt",
+        parameters: [":contributor"],
+        functionAbi: {
+            name: "canDecrypt",
+            type: "function",
+            stateMutability: "view",
+            inputs: [{ internalType: "address", name: "contributor", type: "address" }],
+            outputs: [{ internalType: "bool", name: "", type: "bool" }]
+        },
+        contractAddress: poolAddress,
+        chain: chainId,
+        returnValueTest: { comparator: "==", value: true }
+    };
+}
+export async function encryptWithTaco(params) {
+    const { poolAddress, payload } = params;
+    if (!poolAddress)
+        throw new Error("encryptWithTaco: poolAddress is required");
+    const require = createRequire(import.meta.url);
+    const taco = require("@nucypher/taco");
+    const { initialize, encrypt, domains, conditions } = taco;
+    if (!initialize || !encrypt || !domains || !conditions) {
+        throw new Error("encryptWithTaco: TACo SDK exports missing");
+    }
+    const ContractCondition = conditions?.base?.contract?.ContractCondition;
+    if (!ContractCondition) {
+        throw new Error("encryptWithTaco: ContractCondition not available");
+    }
+    const { key, dkg, condition, conditionChain, ritual } = resolveTacoConfig(params);
+    await initialize();
+    const dkgProvider = new providers.JsonRpcProvider(dkg);
+    const conditionProvider = new providers.JsonRpcProvider(condition);
+    const encryptorSigner = await resolveConditionSigner(conditionProvider, key);
+    const conditionInstance = new ContractCondition({
+        method: "canDecrypt",
+        parameters: [":contributor"],
+        functionAbi: buildTacoCondition(poolAddress, conditionChain).functionAbi,
+        contractAddress: poolAddress,
+        chain: conditionChain,
+        returnValueTest: { comparator: "==", value: true }
+    });
+    const payloadBytes = payload instanceof Uint8Array ? payload : encodePayload(payload);
+    const kit = await encrypt(dkgProvider, domains.TESTNET || domains.tapir, payloadBytes, conditionInstance, ritual, encryptorSigner);
+    if (typeof kit === "string")
+        return kit;
+    if (kit?.toBytes)
+        return toHexString(kit.toBytes());
+    if (kit?.toString)
+        return kit.toString();
+    return JSON.stringify(kit);
+}
+export async function decryptWithTaco(params) {
+    const { messageKit, contributorAddress } = params;
+    if (!messageKit)
+        throw new Error("decryptWithTaco: messageKit is required");
+    const require = createRequire(import.meta.url);
+    const taco = require("@nucypher/taco");
+    const { initialize, decrypt, domains, conditions, ThresholdMessageKit } = taco;
+    if (!initialize || !decrypt || !domains || !conditions || !ThresholdMessageKit) {
+        throw new Error("decryptWithTaco: TACo SDK exports missing");
+    }
+    const ConditionContext = conditions?.context?.ConditionContext;
+    if (!ConditionContext)
+        throw new Error("decryptWithTaco: ConditionContext missing");
+    const { key, condition, conditionChain, ritual, dkg } = resolveTacoConfig(params);
+    await initialize();
+    const conditionProvider = new providers.JsonRpcProvider(condition);
+    const decryptorSigner = await resolveConditionSigner(conditionProvider, key);
+    const decryptorAddress = await decryptorSigner.getAddress();
+    const kitBytes = Buffer.from(messageKit.replace(/^0x/, ""), "hex");
+    const kit = ThresholdMessageKit.fromBytes(Uint8Array.from(kitBytes));
+    const context = ConditionContext.fromMessageKit(kit);
+    context.addCustomContextParameterValues({
+        ":contributor": contributorAddress ? utils.getAddress(contributorAddress) : decryptorAddress
+    });
+    const decryptedBytes = await decrypt(conditionProvider, domains.TESTNET || domains.tapir, kit, context, domains.TESTNET?.porterUris);
+    return new TextDecoder().decode(decryptedBytes);
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@whistlex/sdk",
+  "version": "0.1.0",
+  "description": "WhistleX SDK for local encryption, TACo wrapping, and on-chain pool calldata",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@nucypher/taco": "0.6.0",
+    "ethers": "^5.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "typescript": "^5.3.3"
+  }
+}