fangorn-sdk 0.0.5 → 2026.2.2-4.1

package/README.md

@@ -4,35 +4,61 @@ Programmable data.
 
 ## Overview
 
-Fangorn is a programmable data framework that lets you **register datasources** and **publish encrypted data** under public conditions, or predicates, such that it can only be decrypted if you meet the condition.
+Fangorn is a programmable data framework that lets you **register datasources** and **publish encrypted data** under public conditions, or predicates, such that it can only be decrypted if you meet the condition(s).
 
 ## Supported Networks
 
 Fangorn can be deployed on any EVM chain that has a brige to Lit protocol. Currently, contracts are deployed to both Arbitrum Sepolia and Base Sepolia. See the [contracts](#contracts) section for more info.
 
-## Build
+## Usage
 
-`pnpm i`.
+Fangorn is a programmable data framework. It provides tools to register data sources that can be accessed based on owner-defined conditions, like payment.
 
-### Usage
+## CLI/Quickstart
 
-Fangorn is a programmable data framework. It provides tools to register data sources that can be accessed based on owner-defined conditions, like payment.
+To install the fangorn-sdk from NPM, run:
 
-#### Quickstart
+```shell
+npm i -g fangorn-sdk
+```
 
-```js
-# Coming soon
+### Register a Datasource
+
+First register a datasource 
+
+``` sh
+fangorn register name-of-your-datasource-agent
 ```
 
-#### Full Guide
+### Upload Data
 
-#### Setup
+On upload, data is encrypted under a user-specified **gadget**. For now, the CLI only supports the payment gadget, which is used by specifying the argument `-g "Payment(amount)"`. The minimum amount is `0.000001`.
+
+For `-c`, the CLI supports both arbitrumSepolia and baseSepolia. 
+
+``` sh
+fangorn upload name-of-your-datasource-agent file-to-upload.ext -c arbitrumSepolia -g "Payment(0.0001)"
+```
+
+### Decrypt and Download
+
+``` sh
+fangorn decrypt [owner] [datasourceName] [tag] -c arbitrumSepolia
+```
+
+## Full Guide
+
+### Build
+
+`pnpm i`
+
+### Setup
 
 ```js
 // provide the account, rpcurl, and chain externally
 // Initalize a wallet client
 const walletClient = createWalletClient({
-  account,,
+  account,
   transport: http(rpcUrl),
   chain,
 });
@@ -69,7 +95,7 @@ const fangorn = await Fangorn.init(
 );
 ```
 
-##### Datasource Registration
+### Datasource Registration
 
 Now that you have a Fangorn client, you can create a _datasource_. A datasource is an on-chain asset that stores a commitment to its storage root along with an optional `agentId` field for associating the datasource with an ERC-8004 identity.
 
@@ -79,7 +105,7 @@ const name = "demo";
 const id = await this.delegatorFangorn.registerDataSource(name, "");
 ```
 
-##### Encryption
+### Encryption
 
 Once a datasource exists, the owner can update its storage root to point it to data. Fangorn leverages Lit protocol for encryption and access control.
 
@@ -229,7 +255,7 @@ The tests will:
 To install locally:
 
 ```sh
-chmod +x update_clci.sh
+chmod +x update_cli.sh
 ./update_cli.sh
 ```
 
@@ -243,8 +269,12 @@ Options:
   -h, --help                              display help for command
 
 Commands:
+  init                                    Configure your Fangorn credentials
   register [options] <name>               Register a new datasource as an agent.
   upload [options] <name> <files...>      Upload file(s) to a data source
+  list [options] <name>                   List contents (index) of a data source
+  info [options] <name>                   Get data source info from contract
+  entry [options] <name> <tag>            Get info about a specific entry
   decrypt [options] <owner> <name> <tag>  Decrypt a file from a vault
   help [command]                          display help for command
 ```

package/lib/{cli.js → cli/cli.js}

@@ -1,43 +1,59 @@
 #!/usr/bin/env node
-import getNetwork, { FangornConfig, SupportedNetworks } from "./config.js";
-import { Fangorn } from "./fangorn.js";
-import { PinataStorage } from "./providers/storage/pinata/index.js";
-import { LitEncryptionService } from "./modules/encryption/lit.js";
-import { computeTagCommitment, fieldToHex } from "./utils/index.js";
-import { PaymentGadget } from "./modules/gadgets/payment.js";
-import { agentCardBuilder } from "./builders/a2aCardBuilder.js";
-import { Command } from "commander";
-import { confirm, intro, isCancel, multiselect, note, outro, select, spinner, text } from "@clack/prompts";
+import { FangornConfig, SupportedNetworks } from "../config.js";
+import { Fangorn } from "../fangorn.js";
+import { PinataStorage } from "../providers/storage/pinata/index.js";
+import { computeTagCommitment, fieldToHex } from "../utils/index.js";
+import { LitEncryptionService } from "../modules/encryption/lit.js";
+import { agentCardBuilder } from "../builders/a2aCardBuilder.js";
+import { getChain, handleCancel, parseGadgetArg, selectChain } from "./index.js";
+import { GADGET_REGISTRY, selectGadget } from "./registry.js";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename, extname, join } from "path";
 import { createWalletClient, http } from "viem";
+import { Command } from "commander";
+import { confirm, intro, multiselect, note, outro, select, spinner, text } from "@clack/prompts";
 import { privateKeyToAccount } from "viem/accounts";
-import { createLitClient } from "@lit-protocol/lit-client";
-import { nagaDev } from "@lit-protocol/networks";
-import { readFileSync, writeFileSync } from "fs";
-import { basename, extname } from "path";
 import "dotenv/config";
 import { PinataSDK } from "pinata";
 import { SDK } from "agent0-sdk";
+import { homedir } from "os";
 
-//#region src/cli.ts
+//#region src/cli/cli.ts
+const CONFIG_DIR = join(homedir(), ".fangorn");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 let _config = null;
 let _account = null;
 let _fangorn = null;
 function loadConfig() {
 	if (_config) return _config;
+	const privateKey = process.env.DELEGATOR_ETH_PRIVATE_KEY;
 	const jwt = process.env.PINATA_JWT;
 	const gateway = process.env.PINATA_GATEWAY;
-	const privateKey = process.env.DELEGATOR_ETH_PRIVATE_KEY;
 	const chainName = process.env.CHAIN_NAME;
-	if (!chainName || !jwt || !gateway || !privateKey) throw new Error("Missing required env vars: CHAIN_NAME, PINATA_JWT, PINATA_GATEWAY, DELEGATOR_ETH_PRIVATE_KEY");
-	let config = FangornConfig.BaseSepolia;
-	if (chainName === SupportedNetworks.ArbitrumSepolia.name) config = FangornConfig.ArbitrumSepolia;
-	_config = {
+	if (privateKey && jwt && gateway && chainName) {
+		_config = buildConfig({
+			privateKey,
+			jwt,
+			gateway,
+			chainName
+		});
+		return _config;
+	}
+	if (existsSync(CONFIG_PATH)) {
+		_config = buildConfig(JSON.parse(readFileSync(CONFIG_PATH, "utf-8")));
+		return _config;
+	}
+	throw new Error("No configuration found. Run `fangorn init` to set up your credentials, or set DELEGATOR_ETH_PRIVATE_KEY, PINATA_JWT, PINATA_GATEWAY, and CHAIN_NAME env vars.");
+}
+function buildConfig({ privateKey, jwt, gateway, chainName }) {
+	let cfg = FangornConfig.BaseSepolia;
+	if (chainName === SupportedNetworks.ArbitrumSepolia.name) cfg = FangornConfig.ArbitrumSepolia;
+	return {
+		privateKey,
 		jwt,
 		gateway,
-		privateKey,
-		cfg: config
+		cfg
 	};
-	return _config;
 }
 function getAccount() {
 	if (_account) return _account;
@@ -52,7 +68,6 @@ async function getFangorn(chain) {
 		transport: http(cfg.cfg.rpcUrl),
 		chain
 	});
-	const litClient = await createLitClient({ network: nagaDev });
 	const appConfig = cfg.cfg;
 	const domain = process.env.DOMAIN || "localhost:3000";
 	const storage = new PinataStorage(new PinataSDK({
@@ -60,32 +75,59 @@ async function getFangorn(chain) {
 		pinataGateway: cfg.gateway
 	}));
 	const chainName = process.env.CHAIN_NAME;
-	const encryptionService = new LitEncryptionService(litClient, { chainName });
+	const encryptionService = await LitEncryptionService.init(chainName);
 	_fangorn = await Fangorn.init(walletClient, storage, encryptionService, domain, appConfig);
 	return _fangorn;
 }
-const getChain = (chainStr) => {
-	return getNetwork(chainStr);
-};
-const handleCancel = (value) => {
-	if (isCancel(value)) process.exit(0);
-};
-const selectChain = async () => {
-	const chainChoice = await select({
-		message: "Pick your chain.",
+const program = new Command();
+program.name("Fangorn").description("CLI for Fangorn").version("0.0.1");
+program.command("init").description("Configure your Fangorn credentials").action(async () => {
+	intro("Fangorn Setup");
+	const privateKey = await text({
+		message: "Your wallet private key (stored locally, never transmitted):",
+		placeholder: "0x...",
+		validate: (v) => {
+			if (!v.startsWith("0x") || v.length !== 66) return "Must be a valid 0x-prefixed 32-byte hex key";
+		}
+	});
+	handleCancel(privateKey);
+	const jwt = await text({
+		message: "Pinata JWT:",
+		validate: (v) => {
+			if (!v) return "Required";
+		}
+	});
+	handleCancel(jwt);
+	const gateway = await text({
+		message: "Pinata Gateway URL:",
+		placeholder: "https://your-gateway.mypinata.cloud",
+		validate: (v) => {
+			if (!v) return "Required";
+		}
+	});
+	handleCancel(gateway);
+	const chainName = await select({
+		message: "Default chain:",
 		options: [{
-			value: "arbitrumSepolia",
+			value: SupportedNetworks.ArbitrumSepolia.name,
 			label: "Arbitrum Sepolia"
 		}, {
-			value: "baseSepolia",
+			value: SupportedNetworks.BaseSepolia.name,
 			label: "Base Sepolia"
 		}]
 	});
-	handleCancel(chainChoice);
-	return getNetwork(chainChoice.toString());
-};
-const program = new Command();
-program.name("Fangorn").description("CLI for Fangorn").version("9129129");
+	handleCancel(chainName);
+	const stored = {
+		privateKey,
+		jwt,
+		gateway,
+		chainName
+	};
+	if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+	writeFileSync(CONFIG_PATH, JSON.stringify(stored, null, 2), "utf-8");
+	chmodSync(CONFIG_PATH, 384);
+	outro(`Config saved to ${CONFIG_PATH}`);
+});
 program.command("register").description("Register a new datasource as an agent.").argument("<name>", "Name of the datasource").option("-s, --skip-card", "Skip agent card creation").option("-e, --skip-erc", "Skip ERC-8007 registrion").option("-d, --skip-ds", "Skip datasource registrion").action(async (name, options) => {
 	try {
 		intro("Chain selection");
@@ -334,7 +376,7 @@ program.command("register").description("Register a new datasource as an agent."
 		process.exit(1);
 	}
 });
-program.command("upload").description("Upload file(s) to a data source").argument("<name>", "Data source name").argument("<files...>", "File path(s) to upload").option("-c, --chain <chain>", "The chain to use as the backend (arbitrumSepolia or baseSepolia)").option("-p, --price <price>", "price to access the file").option("--overwrite", "Overwrite existing data source contents").action(async (name, files, options) => {
+program.command("upload").description("Upload file(s) to a data source").argument("<name>", "Data source name").argument("<files...>", "File path(s) to upload").option("-c, --chain <chain>", "The chain to use as the backend (arbitrumSepolia or baseSepolia)").option("-g, --gadget <type(args)>", "Gadget to use (e.g. Payment(0.000001))").option("-o --overwrite", "Overwrite existing data source contents").action(async (name, files, options) => {
 	try {
 		const owner = getAccount().address;
 		const fangorn = await getFangorn(getChain(options.chain));
@@ -351,12 +393,20 @@ program.command("upload").description("Upload file(s) to a data source").argumen
 			};
 		});
 		const cid = await fangorn.upload(name, filedata, async (file) => {
-			return new PaymentGadget({
-				commitment: fieldToHex(await computeTagCommitment(owner, name, file.tag, options.price)),
-				chainName: "arbitrumSepolia",
-				settlementTrackerContractAddress: "0xb32ed201896ba765e6aa118a5c18c263f559474e",
-				usdcPrice: options.price
-			});
+			if (options.gadget) {
+				const { type, args } = parseGadgetArg(options.gadget);
+				const def = GADGET_REGISTRY[type];
+				if (!def) throw new Error(`Unknown gadget type: ${type}`);
+				const params = {};
+				def.argSchema.forEach((key, i) => {
+					params[key] = args[i];
+				});
+				params.commitment = fieldToHex(await computeTagCommitment(owner, name, file.tag, options.price));
+				params.chainName = options.chain;
+				params.settlementTrackerContractAddress = options.chain === "arbitrumSepolia" ? "0x7c6ae9eb3398234eb69b2f3acfae69065505ff69" : "0x708751829f5f5f584da4142b62cd5cc9235c8a18";
+				return def.build(params);
+			}
+			return selectGadget(owner, name, file.tag, options.price);
 		}, options.overwrite);
 		console.log(`Upload complete! Manifest CID: ${cid}`);
 		process.exit(0);
@@ -365,13 +415,61 @@ program.command("upload").description("Upload file(s) to a data source").argumen
 		process.exit(1);
 	}
 });
+program.command("list").description("List contents (index) of a data source").argument("<name>", "Data source name").option("-c, --chain <chain>", "The chain to use as the backend (arbitrumSepolia or baseSepolia)").action(async (name, options) => {
+	try {
+		const owner = getAccount().address;
+		const manifest = await (await getFangorn(getChain(options.chain))).getManifest(owner, name);
+		if (!manifest) {
+			console.log("The data source is empty. \n");
+			console.log("Upload data with `fangorn upload <dataSourceName> <file> --price <set-price>");
+			process.exit(0);
+		}
+		console.log(`Datasource: ${name} (${owner})`);
+		console.log(`Entries (${manifest.entries.length}):`);
+		for (const entry of manifest.entries) console.log(`  - ${entry.tag} | gadget descriptor: ${JSON.stringify(entry.gadgetDescriptor)} | cid: ${entry.cid}`);
+		process.exit(0);
+	} catch (err) {
+		console.error("Failed to list vault:", err.message);
+		process.exit(1);
+	}
+});
+program.command("info").description("Get data source info from contract").argument("<name>", "Data source name").option("-c, --chain <chain>", "The chain to use as the backend (arbitrumSepolia or baseSepolia)").action(async (name, options) => {
+	try {
+		const owner = getAccount().address;
+		const vault = await (await getFangorn(getChain(options.chain))).getDataSource(owner, name);
+		console.log(`Datasource: ${name} (${owner})`);
+		console.log(`Owner: ${vault.owner}`);
+		console.log(`Manifest CID: ${vault.manifestCid == "" ? "Upload data with `fangorn upload <vaultName> <file> --price <set-price>`" : vault.manifestCid}`);
+		process.exit(0);
+	} catch (err) {
+		console.error("Failed to get vault info:", err.message);
+		process.exit(1);
+	}
+});
+program.command("entry").description("Get info about a specific entry").argument("<name>", "Vault name").argument("<tag>", "File tag").option("-c, --chain <chain>", "The chain to use as the backend (arbitrumSepolia or baseSepolia").action(async (name, tag, options) => {
+	try {
+		const owner = getAccount().address;
+		const entry = await (await getFangorn(getChain(options.chain))).getDataSourceData(owner, name, tag);
+		console.log(`Entry: ${tag}`);
+		console.log(`  CID: ${entry.cid}`);
+		console.log(`  Gadget Descriptor: ${JSON.stringify(entry.gadgetDescriptor)}`);
+		process.exit(0);
+	} catch (err) {
+		console.error("Failed to get entry:", err.message);
+		process.exit(1);
+	}
+});
 program.command("decrypt").description("Decrypt a file from a vault").argument("<owner>", "The owner of the datasource").argument("<name>", "The name of the datasource").argument("<tag>", "File tag").option("-c, --chain <chain>", "The chain to use as the backend (arbitrumSepolia or baseSepolia").option("-o, --output <path>", "Output file path").action(async (owner, name, tag, options) => {
 	try {
 		const decrypted = await (await getFangorn(getChain(options.chain))).decryptFile(owner, name, tag);
 		if (options.output) {
 			writeFileSync(options.output, Buffer.from(decrypted));
 			console.log(`Decrypted file saved to: ${options.output}`);
-		} else process.stdout.write(Buffer.from(decrypted));
+		} else {
+			const buf = Buffer.from(decrypted);
+			process.stdout.write(atob(buf.toString()));
+			process.stdout.write("\n");
+		}
 		process.exit(0);
 	} catch (err) {
 		console.error("Failed to decrypt:", err.message);