feat: zero-config SDK experience with hosted Photon proxy and IPFS uploader

- sati-sdk 0.6.0: add createSatiUploader() for hosted IPFS uploads, default
  Photon RPC proxy URLs at sati.cascade.fyi/api/photon/{network}
- sati-agent0-sdk 0.3.0: registerIPFS()/updateIPFS() fall back to hosted
  uploader when pinataJwt is not set, add photonRpcUrl config passthrough
- Worker: add POST /api/photon/:network proxy and POST /api/upload-metadata
  endpoints with per-IP rate limiting and payload size caps
- Docs: rewrite guides for zero-config, update examples to use registerIPFS()
  as default path, restructure navigation

Author: tenequm

apps/dashboard/src/worker/identity-api.ts

@@ -30,6 +30,41 @@ import type { Endpoint, TrustMechanism } from "@cascade-fyi/sati-sdk";
 import bs58 from "bs58";
 import type { Env } from "../env";
 
+// =============================================================================
+// Rate Limiter (per-isolate, best-effort)
+// =============================================================================
+
+/** Per-IP sliding window rate limiter. State lives in module scope (shared within a CF Worker isolate). */
+const rateLimitBuckets = new Map<string, { count: number; resetAt: number }>();
+
+function isRateLimited(key: string, maxRequests: number, windowMs: number): boolean {
+  const now = Date.now();
+  const bucket = rateLimitBuckets.get(key);
+  if (!bucket || now >= bucket.resetAt) {
+    rateLimitBuckets.set(key, { count: 1, resetAt: now + windowMs });
+    return false;
+  }
+  bucket.count++;
+  return bucket.count > maxRequests;
+}
+
+// Periodic cleanup of stale buckets (runs at most once per minute)
+let lastCleanup = 0;
+function cleanupBuckets() {
+  const now = Date.now();
+  if (now - lastCleanup < 60_000) return;
+  lastCleanup = now;
+  for (const [key, bucket] of rateLimitBuckets) {
+    if (now >= bucket.resetAt) rateLimitBuckets.delete(key);
+  }
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const MAX_METADATA_SIZE = 100 * 1024; // 100 KB
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -579,5 +614,87 @@ export function createIdentityApi(env: Env) {
     }
   });
 
+  // ---------------------------------------------------------------------------
+  // POST /api/photon/:network - Photon RPC proxy
+  // ---------------------------------------------------------------------------
+
+  app.post("/api/photon/:network", async (c) => {
+    cleanupBuckets();
+
+    const network = c.req.param("network");
+    if (network !== "devnet" && network !== "mainnet") {
+      return c.json({ error: "Invalid network - must be devnet or mainnet" }, 400);
+    }
+
+    // Rate limit: 120 requests per minute per IP
+    const ip = c.req.header("cf-connecting-ip") ?? c.req.header("x-forwarded-for") ?? "unknown";
+    if (isRateLimited(`photon:${ip}`, 120, 60_000)) {
+      return c.json({ error: "Rate limit exceeded - max 120 requests per minute" }, 429);
+    }
+
+    const rpcUrl = env.RPC_URLS[network].rpc;
+    const body = await c.req.text();
+
+    const response = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+    });
+
+    const result = await response.text();
+    return new Response(result, {
+      status: response.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // POST /api/upload-metadata - Upload metadata JSON to IPFS
+  // ---------------------------------------------------------------------------
+
+  app.post("/api/upload-metadata", async (c) => {
+    cleanupBuckets();
+
+    // Rate limit: 10 uploads per minute per IP
+    const ip = c.req.header("cf-connecting-ip") ?? c.req.header("x-forwarded-for") ?? "unknown";
+    if (isRateLimited(`upload:${ip}`, 10, 60_000)) {
+      return c.json({ error: "Rate limit exceeded - max 10 uploads per minute" }, 429);
+    }
+
+    if (!env.PINATA_JWT) {
+      return c.json({ error: "Server misconfigured: missing PINATA_JWT" }, 500);
+    }
+
+    // Payload size cap
+    const contentLength = Number(c.req.header("content-length") ?? 0);
+    if (contentLength > MAX_METADATA_SIZE) {
+      return c.json({ error: `Payload too large - max ${MAX_METADATA_SIZE / 1024}KB` }, 413);
+    }
+
+    let data: unknown;
+    try {
+      const body = await c.req.text();
+      if (body.length > MAX_METADATA_SIZE) {
+        return c.json({ error: `Payload too large - max ${MAX_METADATA_SIZE / 1024}KB` }, 413);
+      }
+      data = JSON.parse(body);
+    } catch {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+
+    if (!data || typeof data !== "object") {
+      return c.json({ error: "Request body must be a JSON object" }, 400);
+    }
+
+    try {
+      const uploader = createPinataUploader(env.PINATA_JWT);
+      const uri = await uploader.upload(data);
+      return c.json({ uri });
+    } catch (error) {
+      console.error("[upload-metadata] ERROR:", error);
+      return c.json({ error: error instanceof Error ? error.message : "Upload failed" }, 500);
+    }
+  });
+
   return app;
 }

docs/.vitepress/config.ts

@@ -1,54 +1,77 @@
 import { defineConfig } from 'vitepress'
+import llmstxt, { copyOrDownloadAsMarkdownButtons } from 'vitepress-plugin-llms'
 
 export default defineConfig({
+  markdown: {
+    config(md) {
+      md.use(copyOrDownloadAsMarkdownButtons)
+    },
+  },
+
+  vite: {
+    plugins: [llmstxt({ excludeIndexPage: false })],
+  },
+
   title: 'SATI',
-  description: 'Solana Agent Trust Infrastructure - Open trust layer for AI agents',
+  description: 'Solana Agent Trust Infrastructure - On-chain identity and reputation for AI agents',
   base: '/sati/',
 
   head: [
     ['meta', { name: 'theme-color', content: '#14F195' }],
     ['meta', { property: 'og:type', content: 'website' }],
-    ['meta', { property: 'og:title', content: 'SATI - Solana Agent Trust Infrastructure' }],
-    ['meta', { property: 'og:description', content: 'Production-ready agent reputation on Solana. ~$0.002 per attestation.' }],
+    ['meta', { property: 'og:title', content: 'SATI - On-chain identity for AI agents' }],
+    ['meta', { property: 'og:description', content: 'Verifiable track record for AI agents on Solana. Proof of participation, zero infrastructure, ~$0.002 per attestation.' }],
   ],
 
   themeConfig: {
     nav: [
-      { text: 'Guide', link: '/getting-started' },
-      { text: 'Specification', link: '/specification' },
-      { text: 'SDK', link: 'https://www.npmjs.com/package/@cascade-fyi/sati-sdk' },
+      { text: 'Getting Started', link: '/getting-started' },
+      { text: 'Guides', link: '/guides/agent-marketplace' },
+      { text: 'Reference', link: '/reference/' },
       { text: 'GitHub', link: 'https://github.com/cascade-protocol/sati' },
     ],
 
     sidebar: [
       {
-        text: 'Introduction',
+        text: 'Start Here',
         items: [
-          { text: 'What is SATI?', link: '/' },
+          { text: 'Home', link: '/' },
           { text: 'Getting Started', link: '/getting-started' },
+          { text: 'How It Works', link: '/how-it-works' },
         ]
       },
       {
-        text: 'Guide',
+        text: 'Guides',
         items: [
-          { text: 'Core Concepts', link: '/guide/concepts' },
-          { text: 'Agent Registration', link: '/guide/agent-registration' },
-          { text: 'Feedback & Reputation', link: '/guide/feedback' },
-          { text: 'Delegation', link: '/guide/delegation' },
+          { text: 'Agent Marketplace', link: '/guides/agent-marketplace' },
+          { text: 'x402 Payment Feedback', link: '/guides/x402-feedback' },
+          { text: 'Register an MCP Agent', link: '/guides/mcp-agent' },
+          { text: 'Query Reputation', link: '/guides/query-reputation' },
+          { text: 'Browser Wallet Flow', link: '/guides/browser-wallet' },
         ]
       },
       {
-        text: 'Concepts',
+        text: 'API Reference',
         items: [
-          { text: 'Validation', link: '/concepts/validation' },
+          { text: 'Overview', link: '/reference/' },
+          { text: 'sati-agent0-sdk', link: '/reference/sati-agent0-sdk' },
+          { text: 'sati-sdk', link: '/reference/sati-sdk' },
         ]
       },
       {
-        text: 'Reference',
+        text: 'Deep Dive',
         items: [
           { text: 'Specification', link: '/specification' },
         ]
       },
+      {
+        text: 'Advanced',
+        collapsed: true,
+        items: [
+          { text: 'Transaction Sizes', link: '/advanced/transaction-sizes' },
+          { text: 'Compute Unit Benchmarks', link: '/advanced/benchmarks' },
+        ]
+      },
     ],
 
     socialLinks: [

docs/.vitepress/theme/index.ts

@@ -0,0 +1,10 @@
+import DefaultTheme from 'vitepress/theme'
+import type { Theme } from 'vitepress'
+import CopyOrDownloadAsMarkdownButtons from 'vitepress-plugin-llms/vitepress-components/CopyOrDownloadAsMarkdownButtons.vue'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('CopyOrDownloadAsMarkdownButtons', CopyOrDownloadAsMarkdownButtons)
+  },
+} satisfies Theme

docs/benchmarks/compute_units.md docs/advanced/benchmarks.mddocs/benchmarks/compute_units.md renamed to docs/advanced/benchmarks.md

@@ -1,6 +1,11 @@
-#### 2025-12-17 14:50:51.180068 UTC
+---
+title: Compute Unit Benchmarks
+description: CU measurements for all SATI program instructions
+---
 
-Solana CLI Version: solana-cli 3.1.1 (src:7096e605; feat:3652419286, client:Agave)
+# Compute Unit Benchmarks
+
+Measured 2025-12-17 with Solana CLI 3.1.1 (Agave).
 
 | Name | CUs | Delta |
 |------|------|-------|

docs/transaction_size.md docs/advanced/transaction-sizes.mddocs/transaction_size.md renamed to docs/advanced/transaction-sizes.md

@@ -1,4 +1,9 @@
-# SATI Transaction Size Guide
+---
+title: Transaction Sizes
+description: Solana transaction size constraints and how SATI optimizes for them
+---
+
+# Transaction Sizes
 
 Understanding Solana's transaction size constraints and how SATI optimizes for them.
 
@@ -335,4 +340,4 @@ console.log(`Transaction size: ${txBytes.length} bytes`);
 - [Solana Transaction Size Limits](https://solana.com/docs/core/transactions#transaction-size)
 - [Address Lookup Tables](https://solana.com/docs/advanced/lookup-tables)
 - [Ed25519 Instruction Format](https://docs.solanalabs.com/runtime/programs#ed25519-program)
-- [SATI Specification](./specification.md)
+- [SATI Specification](/specification)