fangorn-sdk 2026.2.24 → 2026.2.26

package/README.md

@@ -10,44 +10,62 @@ Fangorn is a programmable data framework that lets you **register datasources**
 
 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:
+
+```shell
+npm i -g fangorn-sdk
+```
 
-#### Quickstart
+### Register a Datasource
 
-```js
-# Coming soon
+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,
 });
-
 // For ArbSep, also supports BaseSepolia (wallet client must match)
 const config: AppConfig = FangornConfig.ArbitrumSepolia;
-
-// setup the Lit client (for encryption)
-const litClient = await createLitClient({
-  network: nagaDev,
-});
 // and the encryption service
-const encryptionService = new LitEncryptionService(delegateeLitClient, {
-  chainName: chain,
-});
+const encryptionService = new LitEncryptionService(chain);
 
 // setup the storage client
 const pinata = new PinataSDK({
@@ -69,7 +87,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 +97,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 +247,7 @@ The tests will:
 To install locally:
 
 ```sh
-chmod +x update_clci.sh
+chmod +x update_cli.sh
 ./update_cli.sh
 ```
 
@@ -243,8 +261,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,23 +1,24 @@
 #!/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 "dotenv/config";
 import { PinataSDK } from "pinata";
 import { SDK } from "agent0-sdk";
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { basename, extname, join } from "path";
 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;
@@ -78,26 +79,6 @@ async function getFangorn(chain) {
 	_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.",
-		options: [{
-			value: "arbitrumSepolia",
-			label: "Arbitrum Sepolia"
-		}, {
-			value: "baseSepolia",
-			label: "Base Sepolia"
-		}]
-	});
-	handleCancel(chainChoice);
-	return getNetwork(chainChoice.toString());
-};
 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 () => {
@@ -395,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));
@@ -412,12 +393,21 @@ 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: "0x7c6ae9eb3398234eb69b2f3acfae69065505ff69",
-				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";
+				params.pinataJwt = loadConfig().jwt;
+				return def.build(params);
+			}
+			return selectGadget(owner, name, file.tag, options.price);
 		}, options.overwrite);
 		console.log(`Upload complete! Manifest CID: ${cid}`);
 		process.exit(0);
@@ -476,7 +466,11 @@ program.command("decrypt").description("Decrypt a file from a vault").argument("
 		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);