@signet-base/cli 0.2.0

package/README.md

@@ -0,0 +1,31 @@
+# Signet CLI
+
+Command-line tool for [Signet](https://signet.sebayaki.com) onchain advertising.
+
+## Usage
+
+```bash
+# List recent spotlight signatures
+npx signet-cli list
+npx signet-cli list -n 10
+
+# Estimate spotlight cost
+npx signet-cli estimate
+npx signet-cli estimate --hours 6
+
+# Post a URL to spotlight (requires wallet)
+npx signet-cli post --url https://example.com --hours 0
+npx signet-cli post --url https://example.com --private-key 0x...
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PRIVATE_KEY` | Wallet private key for posting (alternative to `--private-key`) |
+
+## How It Works
+
+1. **`list`** — Fetches recent signatures from the Signet API
+2. **`estimate`** — Queries the estimated USDC cost for a spotlight placement
+3. **`post`** — Uses the [x402 payment protocol](https://www.x402.org) to pay USDC and place a URL on the spotlight

package/bin/signet.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { list } from "../src/commands/list.js";
+import { post } from "../src/commands/post.js";
+import { estimate } from "../src/commands/estimate.js";
+
+program
+  .name("signet")
+  .description("Signet — onchain advertising CLI")
+  .version("0.2.0");
+
+program
+  .command("list")
+  .description("List recent spotlight signatures")
+  .option("-n, --count <number>", "Number of signatures to show", "5")
+  .option("--base-url <url>", "Signet API base URL", "https://signet.sebayaki.com")
+  .action(list);
+
+program
+  .command("estimate")
+  .description("Estimate USDC cost for spotlight placement")
+  .option("-h, --hours <number>", "Guarantee hours (0-24)", "0")
+  .option("--simulate", "Simulate mode (same as normal for estimate)")
+  .option("--base-url <url>", "Signet API base URL", "https://signet.sebayaki.com")
+  .action(estimate);
+
+program
+  .command("post")
+  .description("Place a URL on the Signet spotlight via x402 payment")
+  .requiredOption("-u, --url <url>", "URL to advertise")
+  .option("-h, --hours <number>", "Guarantee hours (0-24)", "0")
+  .option("-k, --private-key <key>", "Wallet private key (or set PRIVATE_KEY env)")
+  .option("--simulate", "Simulate: show estimate and payment requirements without posting")
+  .option("--base-url <url>", "Signet API base URL", "https://signet.sebayaki.com")
+  .action(post);
+
+program.parse();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@signet-base/cli",
+  "version": "0.2.0",
+  "description": "CLI for Signet onchain advertising — list and post spotlight ads",
+  "type": "module",
+  "bin": {
+    "signet": "./bin/signet.js",
+    "signet-cli": "./bin/signet.js"
+  },
+  "scripts": {
+    "start": "node bin/signet.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@x402/core": "^2.3.0",
+    "@x402/evm": "^2.3.0",
+    "commander": "^13.0.0",
+    "viem": "^2.30.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/api.js

@@ -0,0 +1,33 @@
+/**
+ * Signet API client
+ */
+
+const DEFAULT_BASE_URL = "https://signet.sebayaki.com";
+
+export async function fetchEstimate(guaranteeHours = 0, baseUrl = DEFAULT_BASE_URL) {
+  const res = await fetch(`${baseUrl}/api/x402/estimate?guaranteeHours=${guaranteeHours}`);
+  if (!res.ok) throw new Error(`Estimate failed: ${res.status} ${await res.text()}`);
+  return res.json();
+}
+
+export async function fetchSignatures(startIndex = 0, endIndex = 5, baseUrl = DEFAULT_BASE_URL) {
+  const res = await fetch(
+    `${baseUrl}/api/signature/list?startIndex=${startIndex}&endIndex=${endIndex}`
+  );
+  if (!res.ok) throw new Error(`List failed: ${res.status} ${await res.text()}`);
+  return res.json();
+}
+
+/**
+ * POST to spotlight endpoint. Returns the raw Response for 402 handling.
+ */
+export async function postSpotlightRaw({ url, guaranteeHours, headers = {}, baseUrl = DEFAULT_BASE_URL }) {
+  return fetch(`${baseUrl}/api/x402/spotlight`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: JSON.stringify({ url, guaranteeHours }),
+  });
+}

package/src/commands/estimate.js

@@ -0,0 +1,24 @@
+import { fetchEstimate } from "../api.js";
+
+export async function estimate(opts) {
+  const hours = parseInt(opts.hours);
+
+  try {
+    const data = await fetchEstimate(hours, opts.baseUrl);
+
+    console.log(`\n💰 Signet Spotlight Estimate${opts.simulate ? " (SIMULATE)" : ""}\n`);
+    console.log(`  Guarantee Hours: ${data.guaranteeHours}`);
+    console.log(`  Estimated Cost:  $${data.estimatedUSDC} USDC`);
+    console.log(`  Spotlight Available: ${data.spotlightAvailable ? "✅ Yes" : "❌ No"}`);
+
+    if (data.spotlightRemainingSeconds > 0) {
+      const mins = Math.ceil(data.spotlightRemainingSeconds / 60);
+      console.log(`  Current Guarantee Remaining: ${mins} min`);
+    }
+
+    console.log();
+  } catch (err) {
+    console.error("❌", err.message);
+    process.exit(1);
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,32 @@
+import { fetchSignatures } from "../api.js";
+
+export async function list(opts) {
+  const count = parseInt(opts.count);
+  const endIndex = count;
+
+  try {
+    const { signatures } = await fetchSignatures(0, endIndex, opts.baseUrl);
+
+    if (!signatures?.length) {
+      console.log("No signatures found.");
+      return;
+    }
+
+    console.log(`\n📋 Recent Signet Signatures (${signatures.length})\n`);
+
+    for (const sig of signatures) {
+      const date = new Date(sig.timestamp * 1000).toLocaleDateString();
+      const hunt = (Number(sig.huntAmount) / 1e18).toFixed(2);
+      const title = sig.metadata?.title || "(no title)";
+
+      console.log(`  #${sig.signatureIndex} — ${title}`);
+      console.log(`     URL: ${sig.url}`);
+      console.log(`     HUNT: ${hunt} | Views: ${sig.viewCount} | Clicks: ${sig.clickCount}`);
+      console.log(`     Date: ${date} | Wallet: ${sig.userWallet.slice(0, 8)}...`);
+      console.log();
+    }
+  } catch (err) {
+    console.error("❌", err.message);
+    process.exit(1);
+  }
+}

package/src/commands/post.js

@@ -0,0 +1,110 @@
+import { x402Client, x402HTTPClient } from "@x402/core/client";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+import { fetchEstimate, postSpotlightRaw } from "../api.js";
+
+export async function post(opts) {
+  const privateKey = opts.privateKey || process.env.PRIVATE_KEY;
+  if (!privateKey) {
+    console.error("❌ Wallet private key required. Use --private-key or set PRIVATE_KEY env.");
+    process.exit(1);
+  }
+
+  const hours = parseInt(opts.hours);
+  const url = opts.url;
+  const simulate = opts.simulate || false;
+
+  console.log(`\n🎯 Posting to Signet Spotlight${simulate ? " (SIMULATE)" : ""}`);
+  console.log(`   URL: ${url}`);
+  console.log(`   Guarantee: ${hours}h\n`);
+
+  try {
+    // Step 0: Get estimate
+    console.log("0️⃣  Fetching estimate...");
+    const est = await fetchEstimate(hours, opts.baseUrl);
+    console.log(`   Estimated Cost: $${est.estimatedUSDC} USDC`);
+    console.log(`   Available: ${est.spotlightAvailable ? "Yes" : "No"}\n`);
+
+    if (!est.spotlightAvailable) {
+      console.log(`   ⚠️  Spotlight is currently guaranteed. ${Math.ceil(est.spotlightRemainingSeconds / 60)} min remaining.`);
+    }
+
+    // Step 1: POST without payment to get 402 response
+    console.log("1️⃣  Getting payment requirements...");
+    const res402 = await postSpotlightRaw({
+      url,
+      guaranteeHours: hours,
+      baseUrl: opts.baseUrl,
+    });
+
+    if (res402.status !== 402) {
+      if (res402.ok) {
+        console.log("✅ Posted (no payment was required):", await res402.json());
+      } else {
+        console.error("❌ Unexpected response:", res402.status, await res402.text());
+      }
+      return;
+    }
+
+    // Parse 402 using x402 HTTP client
+    const account = privateKeyToAccount(privateKey);
+    const client = new x402Client();
+    registerExactEvmScheme(client, { signer: account });
+    const httpClient = new x402HTTPClient(client);
+
+    const body402 = await res402.json();
+    const paymentRequired = httpClient.getPaymentRequiredResponse(
+      (name) => res402.headers.get(name),
+      body402
+    );
+
+    const accepts = paymentRequired.accepts?.[0];
+    const displayAmount = accepts?.amount && BigInt(accepts.amount) > 1000000n
+      ? (Number(accepts.amount) / 1e6).toFixed(6)
+      : accepts?.amount;
+    console.log(`   Price: $${displayAmount} USDC`);
+    console.log(`   Pay to: ${accepts?.payTo}`);
+    console.log(`   Network: ${accepts?.network}\n`);
+
+    // Step 2: Create x402 payment signature
+    console.log("2️⃣  Creating x402 payment signature...");
+    console.log(`   Signer: ${account.address}`);
+
+    const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
+    const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+
+    if (simulate) {
+      console.log("\n🔍 SIMULATE MODE — payment signed successfully!");
+      console.log("   Payment payload created and encoded.");
+      console.log("   Would submit with payment headers to execute spotlight placement.");
+      console.log("\n✅ Simulation complete. No payment submitted.\n");
+      return;
+    }
+
+    // Step 3: Submit with payment
+    console.log("\n3️⃣  Submitting with payment...");
+    const resPost = await postSpotlightRaw({
+      url,
+      guaranteeHours: hours,
+      headers: paymentHeaders,
+      baseUrl: opts.baseUrl,
+    });
+
+    if (!resPost.ok) {
+      const err = await resPost.json().catch(() => ({ error: `HTTP ${resPost.status}` }));
+      console.error("❌ Payment rejected:", err.error || JSON.stringify(err));
+      process.exit(1);
+    }
+
+    const result = await resPost.json();
+    console.log("\n✅ Spotlight posted!");
+    console.log(`   TX: ${result.txHash}`);
+    console.log(`   Block: ${result.blockNumber}`);
+    console.log(`   USDC Spent: $${result.usdcSpent}`);
+    console.log(`   URL: ${result.url}`);
+    console.log(`   Guarantee: ${result.guaranteeHours}h\n`);
+  } catch (err) {
+    console.error("❌", err.message);
+    process.exit(1);
+  }
+}

package/test/api.test.js

@@ -0,0 +1,96 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { fetchEstimate, fetchSignatures, postSpotlight } from "../src/api.js";
+
+describe("api", () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  describe("fetchEstimate", () => {
+    it("returns estimate data", async () => {
+      const mockData = {
+        guaranteeHours: 6,
+        estimatedUSDC: "12.28",
+        spotlightAvailable: true,
+        spotlightRemainingSeconds: 0,
+      };
+      global.fetch = async (url) => {
+        assert.ok(url.includes("/api/x402/estimate?guaranteeHours=6"));
+        return { ok: true, json: async () => mockData };
+      };
+      const result = await fetchEstimate(6);
+      assert.deepStrictEqual(result, mockData);
+    });
+
+    it("throws on non-ok response", async () => {
+      global.fetch = async () => ({
+        ok: false,
+        status: 500,
+        text: async () => "Server Error",
+      });
+      await assert.rejects(() => fetchEstimate(0), /Estimate failed: 500/);
+    });
+  });
+
+  describe("fetchSignatures", () => {
+    it("returns signatures", async () => {
+      const mockData = { signatures: [{ signatureIndex: 1 }] };
+      global.fetch = async (url) => {
+        assert.ok(url.includes("startIndex=0&endIndex=5"));
+        return { ok: true, json: async () => mockData };
+      };
+      const result = await fetchSignatures(0, 5);
+      assert.deepStrictEqual(result, mockData);
+    });
+
+    it("throws on error", async () => {
+      global.fetch = async () => ({
+        ok: false,
+        status: 404,
+        text: async () => "Not Found",
+      });
+      await assert.rejects(() => fetchSignatures(), /List failed: 404/);
+    });
+  });
+
+  describe("postSpotlight", () => {
+    it("returns 402 requirements", async () => {
+      const requirements = { x402Version: 2, accepts: [{ amount: "12.28" }] };
+      global.fetch = async () => ({
+        ok: false,
+        status: 402,
+        json: async () => requirements,
+      });
+      const result = await postSpotlight({ url: "https://example.com", guaranteeHours: 0 });
+      assert.strictEqual(result.status, 402);
+      assert.deepStrictEqual(result.requirements, requirements);
+    });
+
+    it("returns 200 on success", async () => {
+      const data = { txHash: "0xabc", url: "https://example.com" };
+      global.fetch = async () => ({
+        ok: true,
+        status: 200,
+        json: async () => data,
+      });
+      const result = await postSpotlight({ url: "https://example.com", guaranteeHours: 0 });
+      assert.strictEqual(result.status, 200);
+      assert.deepStrictEqual(result.data, data);
+    });
+
+    it("includes payment header when provided", async () => {
+      global.fetch = async (url, init) => {
+        assert.strictEqual(init.headers["PAYMENT-SIGNATURE"], "test-header");
+        return { ok: true, status: 200, json: async () => ({}) };
+      };
+      await postSpotlight({ url: "https://example.com", guaranteeHours: 0, paymentHeader: "test-header" });
+    });
+  });
+});

package/test/estimate.test.js

@@ -0,0 +1,58 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { estimate } from "../src/commands/estimate.js";
+
+describe("estimate command", () => {
+  let originalFetch;
+  let output;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+    output = [];
+    const origLog = console.log;
+    console.log = (...args) => output.push(args.join(" "));
+    // Store for restore
+    console._origLog = origLog;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    console.log = console._origLog;
+  });
+
+  it("displays estimate info", async () => {
+    global.fetch = async () => ({
+      ok: true,
+      json: async () => ({
+        guaranteeHours: 6,
+        estimatedUSDC: "12.28",
+        spotlightAvailable: true,
+        spotlightRemainingSeconds: 0,
+      }),
+    });
+
+    await estimate({ hours: "6", baseUrl: "https://signet.sebayaki.com" });
+
+    const text = output.join("\n");
+    assert.ok(text.includes("12.28"), "should show USDC cost");
+    assert.ok(text.includes("6"), "should show hours");
+    assert.ok(text.includes("Yes"), "should show available");
+  });
+
+  it("shows remaining time when applicable", async () => {
+    global.fetch = async () => ({
+      ok: true,
+      json: async () => ({
+        guaranteeHours: 0,
+        estimatedUSDC: "5.00",
+        spotlightAvailable: false,
+        spotlightRemainingSeconds: 3600,
+      }),
+    });
+
+    await estimate({ hours: "0", baseUrl: "https://signet.sebayaki.com" });
+
+    const text = output.join("\n");
+    assert.ok(text.includes("60 min"), "should show remaining minutes");
+  });
+});

package/test/list.test.js

@@ -0,0 +1,61 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { list } from "../src/commands/list.js";
+
+describe("list command", () => {
+  let originalFetch;
+  let output;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+    output = [];
+    const origLog = console.log;
+    console.log = (...args) => output.push(args.join(" "));
+    console._origLog = origLog;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    console.log = console._origLog;
+  });
+
+  it("displays signatures", async () => {
+    global.fetch = async () => ({
+      ok: true,
+      json: async () => ({
+        signatures: [
+          {
+            signatureIndex: 42,
+            url: "https://example.com",
+            huntAmount: "1000000000000000000",
+            viewCount: 100,
+            clickCount: 10,
+            timestamp: 1700000000,
+            userWallet: "0x1234567890abcdef1234567890abcdef12345678",
+            metadata: { title: "Test Ad" },
+          },
+        ],
+      }),
+    });
+
+    await list({ count: "5", baseUrl: "https://signet.sebayaki.com" });
+
+    const text = output.join("\n");
+    assert.ok(text.includes("#42"), "should show signature index");
+    assert.ok(text.includes("Test Ad"), "should show title");
+    assert.ok(text.includes("https://example.com"), "should show URL");
+    assert.ok(text.includes("1.00"), "should show HUNT amount");
+  });
+
+  it("handles empty list", async () => {
+    global.fetch = async () => ({
+      ok: true,
+      json: async () => ({ signatures: [] }),
+    });
+
+    await list({ count: "5", baseUrl: "https://signet.sebayaki.com" });
+
+    const text = output.join("\n");
+    assert.ok(text.includes("No signatures found"), "should show empty message");
+  });
+});

package/test/post.test.js

@@ -0,0 +1,153 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { fetchEstimate, postSpotlight } from "../src/api.js";
+
+describe("post command simulate flow", () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("simulate flow: estimate → 402 → payment requirements extracted", async () => {
+    let fetchCalls = [];
+
+    const paymentRequirements = {
+      x402Version: 2,
+      accepts: [
+        {
+          scheme: "exact",
+          network: "eip155:8453",
+          asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+          amount: "12.28",
+          payTo: "0x78981Ca2f04F97975EaA5b2d69Bc1db50459bDe5",
+          maxTimeoutSeconds: 300,
+          extra: {},
+        },
+      ],
+      resource: {
+        url: "/api/x402/spotlight",
+        description: "Place URL on Signet spotlight",
+        mimeType: "application/json",
+      },
+    };
+
+    global.fetch = async (url, init) => {
+      fetchCalls.push({ url, method: init?.method || "GET" });
+
+      if (url.includes("/api/x402/estimate")) {
+        return {
+          ok: true,
+          json: async () => ({
+            guaranteeHours: 0,
+            estimatedUSDC: "12.28",
+            spotlightAvailable: true,
+            spotlightRemainingSeconds: 0,
+          }),
+        };
+      }
+
+      if (url.includes("/api/x402/spotlight")) {
+        return {
+          ok: false,
+          status: 402,
+          json: async () => paymentRequirements,
+        };
+      }
+
+      throw new Error(`Unexpected fetch: ${url}`);
+    };
+
+    // Step 1: Estimate
+    const est = await fetchEstimate(0);
+    assert.strictEqual(est.estimatedUSDC, "12.28");
+    assert.strictEqual(est.spotlightAvailable, true);
+
+    // Step 2: Post without payment → 402
+    const result = await postSpotlight({ url: "https://example.com", guaranteeHours: 0 });
+    assert.strictEqual(result.status, 402);
+
+    const reqs = result.requirements;
+    assert.strictEqual(reqs.x402Version, 2);
+    assert.strictEqual(reqs.accepts.length, 1);
+    assert.strictEqual(reqs.accepts[0].scheme, "exact");
+    assert.strictEqual(reqs.accepts[0].network, "eip155:8453");
+    assert.strictEqual(reqs.accepts[0].amount, "12.28");
+    assert.strictEqual(reqs.accepts[0].payTo, "0x78981Ca2f04F97975EaA5b2d69Bc1db50459bDe5");
+    assert.strictEqual(reqs.accepts[0].asset, "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+
+    // In simulate mode, we would stop here (no 3rd fetch)
+    assert.strictEqual(fetchCalls.length, 2);
+    assert.strictEqual(fetchCalls[0].method, "GET");
+    assert.strictEqual(fetchCalls[1].method, "POST");
+  });
+
+  it("full flow: estimate → 402 → payment → success", async () => {
+    let fetchCalls = [];
+
+    global.fetch = async (url, init) => {
+      fetchCalls.push({ url, method: init?.method || "GET", hasPayment: !!init?.headers?.["PAYMENT-SIGNATURE"] });
+
+      if (url.includes("/api/x402/estimate")) {
+        return {
+          ok: true,
+          json: async () => ({
+            guaranteeHours: 0,
+            estimatedUSDC: "12.28",
+            spotlightAvailable: true,
+            spotlightRemainingSeconds: 0,
+          }),
+        };
+      }
+
+      if (url.includes("/api/x402/spotlight") && !init?.headers?.["PAYMENT-SIGNATURE"]) {
+        return {
+          ok: false,
+          status: 402,
+          json: async () => ({
+            x402Version: 2,
+            accepts: [{ scheme: "exact", network: "eip155:8453", amount: "12.28", payTo: "0x78981Ca2f04F97975EaA5b2d69Bc1db50459bDe5", asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", maxTimeoutSeconds: 300, extra: {} }],
+          }),
+        };
+      }
+
+      if (url.includes("/api/x402/spotlight") && init?.headers?.["PAYMENT-SIGNATURE"]) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            txHash: "0xabc123",
+            blockNumber: 12345,
+            usdcSpent: "12.28",
+            url: "https://example.com",
+            guaranteeHours: 0,
+          }),
+        };
+      }
+
+      throw new Error(`Unexpected fetch: ${url}`);
+    };
+
+    const est = await fetchEstimate(0);
+    const initial = await postSpotlight({ url: "https://example.com", guaranteeHours: 0 });
+    assert.strictEqual(initial.status, 402);
+
+    // Simulate creating a payment header
+    const paymentHeader = Buffer.from("test-payment").toString("base64");
+
+    const result = await postSpotlight({
+      url: "https://example.com",
+      guaranteeHours: 0,
+      paymentHeader,
+    });
+
+    assert.strictEqual(result.status, 200);
+    assert.strictEqual(result.data.txHash, "0xabc123");
+    assert.strictEqual(fetchCalls.length, 3);
+    assert.strictEqual(fetchCalls[2].hasPayment, true);
+  });
+});