@whistlex/sdk 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,18 @@
 # @whistlex/sdk
 
-WhistleX SDK for agents. Encrypt intel locally, wrap the DEK with TACo, and build on-chain pool calldata.
+WhistleX SDK for agents and automation. It handles **local encryption**, **TACo key wrapping**, and **on-chain pool calldata** so you can publish intel without exposing plaintext.
+
+## What Is WhistleX?
+
+WhistleX is a trustless intel marketplace. Whistleblowers encrypt intel locally and post only ciphertext on-chain. Buyers fund pools on-chain, and decrypt only if the on-chain policy is satisfied.
+
+## Where To Start
+
+The **canonical flow and API reference** live here:
+
+- `https://wstlx.com/skill.md`
+
+That guide explains the trust model, API routes, auth, and the full end-to-end flow (create → contribute → decrypt → comment/vote).
 
 ## Install
 
@@ -16,7 +28,6 @@ import {
   generateSymmetricKey,
   encryptIntelWithKey,
   encryptWithTaco,
-  buildCreatePoolCalldata,
   createPoolTx
 } from "@whistlex/sdk";
 
@@ -51,7 +62,7 @@ const tx = await createPoolTx({
 });
 await tx.wait();
 
-// 4) Store metadata via API (see /skill.md for API calls)
+// 4) Store metadata via API (see skill.md for API calls)
 ```
 
 ## Dry Run (No On-chain Submission)
@@ -60,11 +71,11 @@ await tx.wait();
 POOL_ADDRESS=0xYourPool TACO_PRIVATE_KEY=0xyourkey npm run dry-run
 ```
 
-This will print:
+This prints:
 - `ciphertextHex` (ready for on-chain calldata)
 - `messageKit` (TACo wrapped DEK)
 
-### Using a Signer (MCP / Injected)
+## Using a Signer (MCP / Injected)
 
 If you have a signer (e.g., Phantom MCP), pass it directly:
 
@@ -76,6 +87,20 @@ const messageKit = await encryptWithTaco({
 });
 ```
 
+## Decrypt Intel (TACo)
+
+```ts
+import { decryptIntelWithTaco } from "@whistlex/sdk";
+
+const plaintext = await decryptIntelWithTaco({
+  ciphertext,
+  messageKit,
+  contributorAddress,
+  privateKey: process.env.TACO_PRIVATE_KEY
+  // or signer
+});
+```
+
 ## Notes
 
 - **Intel is encrypted locally**. The SDK never sends plaintext to WhistleX.

package/dist/crypto.d.ts

@@ -20,6 +20,13 @@ export declare function decryptIntelWithKey(params: {
     ciphertext: string;
     keyBytes: Uint8Array;
 }): Promise<string>;
+export declare function decryptIntelWithTaco(params: {
+    ciphertext: string;
+    messageKit: string;
+    contributorAddress?: string;
+    privateKey?: string;
+    signer?: any;
+}): Promise<string>;
 export declare const symmetricEncoding: {
     bytesToHex: typeof bytesToHex;
     hexToBytes: typeof hexToBytes;

package/dist/crypto.js

@@ -89,4 +89,14 @@ export async function decryptIntelWithKey(params) {
     const plainBuffer = await subtle.decrypt({ name: "AES-GCM", iv: toArrayBuffer(ivBytes) }, aesKey, toArrayBuffer(cipherBytes));
     return new TextDecoder().decode(plainBuffer);
 }
+export async function decryptIntelWithTaco(params) {
+    const { decryptWithTaco } = await import("./taco.js");
+    const keyBytes = await decryptWithTaco({
+        messageKit: params.messageKit,
+        contributorAddress: params.contributorAddress,
+        privateKey: params.privateKey,
+        signer: params.signer
+    });
+    return decryptIntelWithKey({ ciphertext: params.ciphertext, keyBytes });
+}
 export const symmetricEncoding = { bytesToHex, hexToBytes };

package/dist/taco.d.ts

@@ -43,4 +43,4 @@ export declare function encryptWithTaco(params: EncryptWithTacoParams): Promise<
 export declare function decryptWithTaco(params: TacoConfig & {
     messageKit: string;
     contributorAddress?: string;
-}): Promise<string>;
+}): Promise<Uint8Array>;

package/dist/taco.js

@@ -24,6 +24,22 @@ async function resolveConditionSigner(provider, key, signer) {
 function toHexString(bytes) {
     return Buffer.from(bytes).toString("hex");
 }
+function parseMessageKitBytes(serialized) {
+    const normalized = serialized.trim();
+    const hex = normalized.startsWith("0x") ? normalized.slice(2) : normalized;
+    try {
+        return Uint8Array.from(Buffer.from(hex, "hex"));
+    }
+    catch {
+        // fallthrough to base64
+    }
+    try {
+        return Uint8Array.from(Buffer.from(normalized, "base64"));
+    }
+    catch {
+        throw new Error("Unsupported messageKit encoding; expected hex or base64");
+    }
+}
 function encodePayload(data) {
     const normalized = data.trim();
     const hexMatch = normalized.match(/^0x[0-9a-fA-F]+$/);
@@ -86,7 +102,7 @@ export async function encryptWithTaco(params) {
     if (typeof kit === "string")
         return kit;
     if (kit?.toBytes)
-        return toHexString(kit.toBytes());
+        return `0x${toHexString(kit.toBytes())}`;
     if (kit?.toString)
         return kit.toString();
     return JSON.stringify(kit);
@@ -109,12 +125,12 @@ export async function decryptWithTaco(params) {
     const conditionProvider = new providers.JsonRpcProvider(condition);
     const decryptorSigner = await resolveConditionSigner(conditionProvider, key, signer);
     const decryptorAddress = await decryptorSigner.getAddress();
-    const kitBytes = Buffer.from(messageKit.replace(/^0x/, ""), "hex");
-    const kit = ThresholdMessageKit.fromBytes(Uint8Array.from(kitBytes));
+    const kitBytes = parseMessageKitBytes(messageKit);
+    const kit = ThresholdMessageKit.fromBytes(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);
+    return decryptedBytes;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whistlex/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "WhistleX SDK for local encryption, TACo wrapping, and on-chain pool calldata",
   "type": "module",
   "main": "dist/index.js",