@sage-protocol/sdk 0.1.6 → 0.1.7

package/dist/node/index.cjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@sage-protocol/sdk",
-      version: "0.1.6",
+      version: "0.1.4",
       description: "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
       main: "dist/index.cjs",
       module: "dist/index.mjs",
@@ -50,10 +50,10 @@ var require_package = __commonJS({
       ],
       sideEffects: false,
       browser: {
+        child_process: false,
         fs: false,
-        path: false,
         os: false,
-        child_process: false
+        path: false
       },
       repository: {
         type: "git",
@@ -82,6 +82,18 @@ var require_package = __commonJS({
         sinon: "^17.0.1",
         tsup: "^8.1.0",
         typescript: "^5.4.0"
+      },
+      peerDependencies: {
+        react: "^18.0.0 || ^19.0.0",
+        swr: "^2.0.0"
+      },
+      peerDependenciesMeta: {
+        react: {
+          optional: true
+        },
+        swr: {
+          optional: true
+        }
       }
     };
   }
@@ -244,19 +256,20 @@ var require_abi = __commonJS({
     var PersonalLicenseReceipt = [
       "function balanceOf(address account, uint256 id) view returns (uint256)"
     ];
-    var TreasuryWrapper = [
-      "function execute(address,uint256,bytes,bytes32) returns (bool)",
-      "function allowedTargets(address) view returns (bool)",
-      "function allowedSelectors(bytes4) view returns (bool)",
-      "function owners(address) view returns (bool)",
-      "function ownerCount() view returns (uint256)",
-      "function registry() view returns (address)",
-      "event TreasuryAction(address indexed caller, address indexed target, uint256 value, bytes data, bytes32 refId)",
-      "event AllowedTargetUpdated(address indexed target, bool allowed)",
-      "event AllowedSelectorUpdated(bytes4 indexed selector, bool allowed)",
-      "event OwnerAdded(address indexed owner)",
-      "event OwnerRemoved(address indexed owner)",
-      "event TokensSwept(address indexed token, address indexed to, uint256 amount)"
+    var SageTreasury = [
+      "function totalReserves() view returns (uint256)",
+      "function totalPOL() view returns (uint256)",
+      "function totalDebt() view returns (uint256)",
+      "function canonicalPool() view returns (address)",
+      "function routerOrVault() view returns (address)",
+      "function maxWithdrawalRate() view returns (uint256)",
+      "function emergencyWithdrawalLimit() view returns (uint256)",
+      "function getReserveTokens() view returns (address[])",
+      "function getReserve(address token) view returns (address tokenAddress,uint256 amount,uint256 value,bool isLP,bool isActive)",
+      "function pendingWithdrawals(uint256) view returns (address token,address recipient,uint256 amount,uint256 value,address requester,uint256 balanceBefore,uint256 recipientBalanceBefore,uint256 depositSnapshot,bool isLP,bool isEmergency,bool exists)",
+      "function nextWithdrawalId() view returns (uint256)",
+      "function manualPrices(address token) view returns (uint256 price,uint256 expiresAt,bool active)",
+      "function lpContributions(address,address) view returns (uint256)"
     ];
     var GovernanceBoostMerkle = [
       "function getProposalConfig(uint256) view returns (tuple(uint256 proposalId,address token,uint256 totalAmount,uint64 startTime,uint64 endTime,uint256 merkleRoot))",
@@ -268,6 +281,29 @@ var require_abi = __commonJS({
       "function create(uint256 proposalId, address token, uint256 perVoter, uint256 maxVoters)",
       "function fund(uint256 proposalId, uint256 amount)"
     ];
+    var BondDepository = [
+      // Core getters
+      "function payoutToken() view returns (address)",
+      "function principalToken() view returns (address)",
+      "function treasury() view returns (address)",
+      // Terms
+      "function terms() view returns (tuple(uint256 controlVariable,uint256 minimumPrice,uint256 maxPayout,uint256 maxDebt,uint256 vestingTerm,uint256 fee))",
+      "function totalDebt(address) view returns (uint256)",
+      // Pricing
+      "function bondPrice() view returns (uint256)",
+      "function bondPrice(address) view returns (uint256)",
+      "function bondPriceInUSD() view returns (uint256)",
+      "function currentDebt() view returns (uint256)",
+      "function debtRatio() view returns (uint256)",
+      "function standardizedDebtRatio() view returns (uint256)",
+      // User views
+      "function bondInfo(address) view returns (tuple(uint256 payout,uint256 vesting,uint256 lastBlock,uint256 pricePaid))",
+      "function pendingPayout(address) view returns (uint256)",
+      "function percentVestedFor(address) view returns (uint256)",
+      // Actions
+      "function deposit(uint256 _amount, uint256 _maxPrice) returns (uint256 payout_)",
+      "function redeem(address _recipient, bool _stake) returns (uint256)"
+    ];
     var Events = {
       ProposalCreated: "event ProposalCreated(uint256 id, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 startBlock, uint256 endBlock, string description)"
     };
@@ -286,10 +322,10 @@ var require_abi = __commonJS({
       PersonalLibraryFacet,
       PersonalMarketplace,
       PersonalLicenseReceipt,
-      TreasuryWrapper,
-      // Protocol treasury (replaces SageTreasury)
+      SageTreasury,
       GovernanceBoostMerkle,
       GovernanceBoostDirect,
+      BondDepository,
       Events
     };
   }
@@ -8087,6 +8123,952 @@ var require_doppler = __commonJS({
   }
 });
 
+// src/services/utils/cache.js
+var require_cache = __commonJS({
+  "src/services/utils/cache.js"(exports2, module2) {
+    var SimpleCache = class {
+      constructor(options = {}) {
+        this.enabled = options.enabled !== false;
+        this.defaultTTL = options.ttl || 3e4;
+        this.maxSize = options.maxSize || 100;
+        this._store = /* @__PURE__ */ new Map();
+      }
+      /**
+       * Get value from cache
+       * @param {string} key - Cache key
+       * @returns {any|null} - Cached value or null if expired/missing
+       */
+      get(key) {
+        if (!this.enabled) return null;
+        const entry = this._store.get(key);
+        if (!entry) return null;
+        if (Date.now() > entry.expires) {
+          this._store.delete(key);
+          return null;
+        }
+        return entry.data;
+      }
+      /**
+       * Set value in cache with TTL
+       * @param {string} key - Cache key
+       * @param {any} data - Data to cache
+       * @param {number} ttl - Time to live in milliseconds (optional)
+       */
+      set(key, data, ttl) {
+        if (!this.enabled) return;
+        if (this._store.size >= this.maxSize && !this._store.has(key)) {
+          const firstKey = this._store.keys().next().value;
+          this._store.delete(firstKey);
+        }
+        this._store.set(key, {
+          data,
+          expires: Date.now() + (ttl || this.defaultTTL)
+        });
+      }
+      /**
+       * Clear all cached entries
+       */
+      clear() {
+        this._store.clear();
+      }
+      /**
+       * Delete specific key
+       * @param {string} key - Cache key to delete
+       */
+      delete(key) {
+        this._store.delete(key);
+      }
+      /**
+       * Get cache statistics
+       * @returns {object} - Cache stats (size, enabled)
+       */
+      stats() {
+        return {
+          size: this._store.size,
+          maxSize: this.maxSize,
+          enabled: this.enabled
+        };
+      }
+    };
+    module2.exports = { SimpleCache };
+  }
+});
+
+// src/services/utils/retry.js
+var require_retry = __commonJS({
+  "src/services/utils/retry.js"(exports2, module2) {
+    async function retryWithBackoff(fn, options = {}) {
+      const {
+        attempts = 3,
+        baseDelay = 1e3,
+        maxDelay = 1e4,
+        onRetry = null
+      } = options;
+      let lastError;
+      for (let i = 0; i < attempts; i++) {
+        try {
+          return await fn();
+        } catch (error) {
+          lastError = error;
+          if (i === attempts - 1) {
+            break;
+          }
+          const delay = Math.min(baseDelay * Math.pow(2, i), maxDelay);
+          if (onRetry) {
+            onRetry({
+              attempt: i + 1,
+              totalAttempts: attempts,
+              delay,
+              error
+            });
+          }
+          await sleep(delay);
+        }
+      }
+      throw lastError;
+    }
+    function sleep(ms) {
+      return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    module2.exports = { retryWithBackoff, sleep };
+  }
+});
+
+// src/errors/index.js
+var require_errors2 = __commonJS({
+  "src/errors/index.js"(exports2, module2) {
+    var SageSDKError = class extends Error {
+      constructor(message, code, retryable = false, originalError = null) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.retryable = retryable;
+        this.originalError = originalError;
+      }
+    };
+    var SubgraphError = class extends SageSDKError {
+      /**
+       * @param {string} message - Error message
+       * @param {'TIMEOUT'|'NETWORK'|'INVALID_RESPONSE'|'NOT_FOUND'|'QUERY_FAILED'} code - Error code
+       * @param {boolean} retryable - Whether error is retryable
+       * @param {Error} originalError - Original error (optional)
+       */
+      constructor(message, code, retryable = false, originalError = null) {
+        super(message, code, retryable, originalError);
+      }
+    };
+    var IPFSError = class extends SageSDKError {
+      /**
+       * @param {string} message - Error message
+       * @param {'TIMEOUT'|'PIN_FAILED'|'INVALID_CID'|'NOT_FOUND'|'GATEWAY_FAILED'|'UPLOAD_FAILED'} code - Error code
+       * @param {boolean} retryable - Whether error is retryable
+       * @param {Error} originalError - Original error (optional)
+       */
+      constructor(message, code, retryable = false, originalError = null) {
+        super(message, code, retryable, originalError);
+      }
+    };
+    function formatErrorMessage(error) {
+      if (!error) return "An unknown error occurred";
+      if (error instanceof SubgraphError || error instanceof IPFSError) {
+        switch (error.code) {
+          case "TIMEOUT":
+            return "Request timed out. Please try again.";
+          case "NETWORK":
+            return "Network error. Check your connection and try again.";
+          case "INVALID_RESPONSE":
+            return "Received invalid data from server.";
+          case "NOT_FOUND":
+            return "Content not found.";
+          case "PIN_FAILED":
+            return "Failed to pin content to IPFS. Please try again.";
+          case "INVALID_CID":
+            return "Invalid content identifier (CID).";
+          case "GATEWAY_FAILED":
+            return "All IPFS gateways failed. Content may be temporarily unavailable.";
+          case "UPLOAD_FAILED":
+            return "Failed to upload content. Please try again.";
+          case "QUERY_FAILED":
+            return "Failed to query data. Please try again.";
+          default:
+            return error.message || "An error occurred";
+        }
+      }
+      return error.message || "An error occurred";
+    }
+    function isRetryable(error) {
+      if (error instanceof SageSDKError) {
+        return error.retryable;
+      }
+      if (error.name === "AbortError" || error.name === "TimeoutError") {
+        return true;
+      }
+      const message = String(error.message || "").toLowerCase();
+      const retryablePatterns = [
+        "timeout",
+        "network",
+        "econnrefused",
+        "econnreset",
+        "etimedout",
+        "fetch failed"
+      ];
+      return retryablePatterns.some((pattern) => message.includes(pattern));
+    }
+    module2.exports = {
+      SageSDKError,
+      SubgraphError,
+      IPFSError,
+      formatErrorMessage,
+      isRetryable
+    };
+  }
+});
+
+// src/services/subgraph/client.js
+var require_client = __commonJS({
+  "src/services/subgraph/client.js"(exports2, module2) {
+    var subgraph = require_subgraph();
+    var { SimpleCache } = require_cache();
+    var { retryWithBackoff } = require_retry();
+    var { SubgraphError } = require_errors2();
+    var SubgraphService = class {
+      /**
+       * @param {object} config - Service configuration
+       * @param {string} config.url - Subgraph GraphQL endpoint
+       * @param {number} [config.timeout=10000] - Request timeout in ms
+       * @param {number} [config.retries=3] - Number of retry attempts
+       * @param {object} [config.cache] - Cache configuration
+       * @param {boolean} [config.cache.enabled=true] - Enable caching
+       * @param {number} [config.cache.ttl=30000] - Cache TTL in ms
+       * @param {number} [config.cache.maxSize=100] - Max cache entries
+       */
+      constructor(config) {
+        if (!config || !config.url) {
+          throw new Error("SubgraphService requires a url in config");
+        }
+        this.url = config.url;
+        this.timeout = config.timeout || 1e4;
+        this.retries = config.retries || 3;
+        this._cache = new SimpleCache({
+          enabled: config.cache?.enabled !== false,
+          ttl: config.cache?.ttl || 3e4,
+          maxSize: config.cache?.maxSize || 100
+        });
+      }
+      /**
+       * Get list of SubDAOs
+       * @param {object} [options] - Query options
+       * @param {number} [options.limit=50] - Max results
+       * @param {number} [options.skip=0] - Results to skip
+       * @param {boolean} [options.cache=true] - Use cache
+       * @returns {Promise<Array>} - List of SubDAOs
+       */
+      async getSubDAOs(options = {}) {
+        const { limit = 50, skip = 0, cache = true } = options;
+        const cacheKey = `subdaos:${limit}:${skip}`;
+        if (cache) {
+          const cached = this._cache.get(cacheKey);
+          if (cached) return cached;
+        }
+        try {
+          const result = await retryWithBackoff(
+            () => this._querySubDAOs({ limit, skip }),
+            { attempts: this.retries }
+          );
+          if (cache) {
+            this._cache.set(cacheKey, result);
+          }
+          return result;
+        } catch (error) {
+          throw new SubgraphError(
+            `Failed to fetch SubDAOs: ${error.message}`,
+            "QUERY_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Get list of proposals
+       * @param {object} [options] - Query options
+       * @param {string} [options.governor] - Filter by governor address
+       * @param {string} [options.subdao] - Filter by SubDAO address
+       * @param {string[]} [options.states] - Filter by proposal states
+       * @param {number} [options.fromTimestamp] - Filter by creation time (>=)
+       * @param {number} [options.toTimestamp] - Filter by creation time (<=)
+       * @param {number} [options.limit=20] - Max results
+       * @param {number} [options.skip=0] - Results to skip
+       * @param {boolean} [options.cache=true] - Use cache
+       * @returns {Promise<Array>} - List of proposals
+       */
+      async getProposals(options = {}) {
+        const {
+          governor,
+          subdao,
+          states,
+          fromTimestamp,
+          toTimestamp,
+          limit = 20,
+          skip = 0,
+          cache = true
+        } = options;
+        const cacheKey = `proposals:${JSON.stringify({
+          governor,
+          subdao,
+          states,
+          fromTimestamp,
+          toTimestamp,
+          limit,
+          skip
+        })}`;
+        if (cache) {
+          const cached = this._cache.get(cacheKey);
+          if (cached) return cached;
+        }
+        try {
+          const result = await retryWithBackoff(
+            () => this._queryProposals({
+              governor,
+              subdao,
+              states,
+              fromTimestamp,
+              toTimestamp,
+              limit,
+              skip
+            }),
+            { attempts: this.retries }
+          );
+          if (cache) {
+            this._cache.set(cacheKey, result);
+          }
+          return result;
+        } catch (error) {
+          throw new SubgraphError(
+            `Failed to fetch proposals: ${error.message}`,
+            "QUERY_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Get proposal by ID
+       * @param {string} id - Proposal ID
+       * @param {object} [options] - Query options
+       * @param {boolean} [options.cache=true] - Use cache
+       * @returns {Promise<object|null>} - Proposal or null
+       */
+      async getProposalById(id2, options = {}) {
+        const { cache = true } = options;
+        const cacheKey = `proposal:${id2}`;
+        if (cache) {
+          const cached = this._cache.get(cacheKey);
+          if (cached !== null) return cached;
+        }
+        try {
+          const result = await retryWithBackoff(
+            () => subgraph.getProposalById({ url: this.url, id: id2 }),
+            { attempts: this.retries }
+          );
+          if (cache) {
+            this._cache.set(cacheKey, result);
+          }
+          return result;
+        } catch (error) {
+          throw new SubgraphError(
+            `Failed to fetch proposal ${id2}: ${error.message}`,
+            "QUERY_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Get libraries
+       * @param {object} [options] - Query options
+       * @param {string} [options.subdao] - Filter by SubDAO address
+       * @param {number} [options.limit=50] - Max results
+       * @param {number} [options.skip=0] - Results to skip
+       * @param {boolean} [options.cache=true] - Use cache
+       * @returns {Promise<Array>} - List of libraries
+       */
+      async getLibraries(options = {}) {
+        const { subdao, limit = 50, skip = 0, cache = true } = options;
+        const cacheKey = `libraries:${subdao || "all"}:${limit}:${skip}`;
+        if (cache) {
+          const cached = this._cache.get(cacheKey);
+          if (cached) return cached;
+        }
+        try {
+          const result = await retryWithBackoff(
+            () => subgraph.listLibraries({ url: this.url, subdao, first: limit, skip }),
+            { attempts: this.retries }
+          );
+          if (cache) {
+            this._cache.set(cacheKey, result);
+          }
+          return result;
+        } catch (error) {
+          throw new SubgraphError(
+            `Failed to fetch libraries: ${error.message}`,
+            "QUERY_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Get prompts by tag
+       * @param {object} options - Query options
+       * @param {string} options.tagsHash - Tag hash to filter by
+       * @param {string} [options.registry] - Filter by registry address
+       * @param {number} [options.limit=50] - Max results
+       * @param {number} [options.skip=0] - Results to skip
+       * @param {boolean} [options.cache=true] - Use cache
+       * @returns {Promise<Array>} - List of prompts
+       */
+      async getPromptsByTag(options) {
+        if (!options || !options.tagsHash) {
+          throw new Error("tagsHash is required");
+        }
+        const { tagsHash, registry, limit = 50, skip = 0, cache = true } = options;
+        const cacheKey = `prompts-tag:${tagsHash}:${registry || "all"}:${limit}:${skip}`;
+        if (cache) {
+          const cached = this._cache.get(cacheKey);
+          if (cached) return cached;
+        }
+        try {
+          const result = await retryWithBackoff(
+            () => subgraph.listPromptsByTag({
+              url: this.url,
+              tagsHash,
+              registry,
+              first: limit,
+              skip
+            }),
+            { attempts: this.retries }
+          );
+          if (cache) {
+            this._cache.set(cacheKey, result);
+          }
+          return result;
+        } catch (error) {
+          throw new SubgraphError(
+            `Failed to fetch prompts by tag: ${error.message}`,
+            "QUERY_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Get registry prompts
+       * @param {object} options - Query options
+       * @param {string} options.registry - Registry address
+       * @param {number} [options.limit=50] - Max results
+       * @param {number} [options.skip=0] - Results to skip
+       * @param {boolean} [options.cache=true] - Use cache
+       * @returns {Promise<Array>} - List of prompts
+       */
+      async getRegistryPrompts(options) {
+        if (!options || !options.registry) {
+          throw new Error("registry is required");
+        }
+        const { registry, limit = 50, skip = 0, cache = true } = options;
+        const cacheKey = `registry-prompts:${registry}:${limit}:${skip}`;
+        if (cache) {
+          const cached = this._cache.get(cacheKey);
+          if (cached) return cached;
+        }
+        try {
+          const result = await retryWithBackoff(
+            () => subgraph.listRegistryPrompts({
+              url: this.url,
+              registry,
+              first: limit,
+              skip
+            }),
+            { attempts: this.retries }
+          );
+          if (cache) {
+            this._cache.set(cacheKey, result);
+          }
+          return result;
+        } catch (error) {
+          throw new SubgraphError(
+            `Failed to fetch registry prompts: ${error.message}`,
+            "QUERY_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Clear cache
+       */
+      clearCache() {
+        this._cache.clear();
+      }
+      /**
+       * Get cache statistics
+       * @returns {object} - Cache stats
+       */
+      getCacheStats() {
+        return this._cache.stats();
+      }
+      // Private methods
+      async _querySubDAOs({ limit, skip }) {
+        const data = await subgraph.query(
+          this.url,
+          `
+      query($first: Int!, $skip: Int!) {
+        subDAOs(first: $first, skip: $skip, orderBy: createdAt, orderDirection: desc) {
+          id
+          address
+          name
+          description
+          governor
+          registry
+          token
+          createdAt
+        }
+      }
+    `,
+          { first: limit, skip }
+        );
+        return data?.subDAOs || [];
+      }
+      async _queryProposals({ governor, subdao, states, fromTimestamp, toTimestamp, limit, skip }) {
+        return await subgraph.listProposalsFiltered({
+          url: this.url,
+          governor,
+          states,
+          fromTimestamp,
+          toTimestamp,
+          first: limit,
+          skip
+        });
+      }
+    };
+    module2.exports = { SubgraphService };
+  }
+});
+
+// src/services/ipfs/client.js
+var require_client2 = __commonJS({
+  "src/services/ipfs/client.js"(exports2, module2) {
+    var ipfs = require_ipfs();
+    var { SimpleCache } = require_cache();
+    var { retryWithBackoff } = require_retry();
+    var { IPFSError } = require_errors2();
+    var IPFSService = class {
+      /**
+       * @param {object} config - Service configuration
+       * @param {string} config.workerBaseUrl - IPFS worker base URL
+       * @param {string} config.gateway - Primary IPFS gateway URL
+       * @param {object} [config.signer] - ethers v6 signer for worker auth
+       * @param {Function} [config.getAuth] - Function to get auth credentials
+       * @param {string} [config.workerToken] - Bearer token for worker auth
+       * @param {number} [config.timeout=15000] - Request timeout in ms
+       * @param {number} [config.retries=2] - Number of retry attempts
+       * @param {object} [config.cache] - Cache configuration
+       * @param {boolean} [config.cache.enabled=true] - Enable caching
+       * @param {number} [config.cache.ttl=300000] - Cache TTL in ms (default 5min for immutable CIDs)
+       * @param {number} [config.cache.maxSize=50] - Max cache entries
+       */
+      constructor(config) {
+        if (!config) {
+          throw new Error("IPFSService requires a config object");
+        }
+        this.workerBaseUrl = config.workerBaseUrl;
+        this.gateway = config.gateway;
+        this.timeout = config.timeout || 15e3;
+        this.retries = config.retries || 2;
+        this._client = ipfs.createClient({
+          workerBaseUrl: config.workerBaseUrl,
+          gateway: config.gateway,
+          workerSigner: config.signer,
+          workerGetAuth: config.getAuth,
+          workerToken: config.workerToken,
+          timeoutMs: this.timeout,
+          retries: this.retries
+        });
+        this._cache = new SimpleCache({
+          enabled: config.cache?.enabled !== false,
+          ttl: config.cache?.ttl || 3e5,
+          // 5 minutes
+          maxSize: config.cache?.maxSize || 50
+        });
+      }
+      /**
+       * Upload content to IPFS worker
+       * @param {any} content - Content to upload (will be JSON stringified)
+       * @param {object} [options] - Upload options
+       * @param {string} [options.name] - Content name
+       * @param {boolean} [options.warm=false] - Warm gateways after upload
+       * @returns {Promise<string>} - CID of uploaded content
+       */
+      async upload(content, options = {}) {
+        const { name = "upload", warm = false } = options;
+        try {
+          const result = await retryWithBackoff(
+            () => this._client.uploadJson(content, name, {
+              provider: "worker",
+              warm
+            }),
+            { attempts: this.retries }
+          );
+          return result.cid;
+        } catch (error) {
+          throw new IPFSError(
+            `Failed to upload content: ${error.message}`,
+            "UPLOAD_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Fetch JSON content by CID with parallel gateway fetching
+       * @param {string} cid - IPFS CID
+       * @param {object} [options] - Fetch options
+       * @param {boolean} [options.cache=true] - Use cache
+       * @param {number} [options.timeout=5000] - Timeout per gateway in ms
+       * @param {string[]} [options.extraGateways] - Additional gateways to try
+       * @returns {Promise<any|null>} - Parsed JSON content or null
+       */
+      async fetchByCID(cid, options = {}) {
+        if (!cid) {
+          throw new IPFSError("CID is required", "INVALID_CID", false);
+        }
+        const { cache = true, timeout = 5e3, extraGateways = [] } = options;
+        if (cache) {
+          const cached = this._cache.get(cid);
+          if (cached) return cached;
+        }
+        const urls = this._client.buildGatewayUrls(cid, extraGateways);
+        try {
+          const result = await this._parallelFetch(urls, timeout);
+          if (result === null) {
+            throw new IPFSError(
+              `All gateways failed for CID ${cid}`,
+              "GATEWAY_FAILED",
+              true
+            );
+          }
+          if (cache) {
+            this._cache.set(cid, result);
+          }
+          return result;
+        } catch (error) {
+          if (error instanceof IPFSError) throw error;
+          throw new IPFSError(
+            `Failed to fetch CID ${cid}: ${error.message}`,
+            "GATEWAY_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Pin CIDs to IPFS worker
+       * @param {string|string[]} cids - CID or array of CIDs to pin
+       * @param {object} [options] - Pin options
+       * @param {boolean} [options.warm=false] - Warm gateways after pinning
+       * @returns {Promise<void>}
+       */
+      async pin(cids, options = {}) {
+        const { warm = false } = options;
+        const cidList = Array.isArray(cids) ? cids : [cids];
+        if (cidList.length === 0) {
+          throw new IPFSError("At least one CID is required", "INVALID_CID", false);
+        }
+        try {
+          await retryWithBackoff(
+            () => this._client.pin({ cids: cidList, warm }),
+            { attempts: this.retries }
+          );
+        } catch (error) {
+          throw new IPFSError(
+            `Failed to pin CIDs: ${error.message}`,
+            "PIN_FAILED",
+            true,
+            error
+          );
+        }
+      }
+      /**
+       * Warm gateways for a CID (prefetch)
+       * @param {string} cid - CID to warm
+       * @param {object} [options] - Warm options
+       * @param {string[]} [options.gateways] - Specific gateways to warm
+       * @returns {Promise<object>} - Warm result
+       */
+      async warm(cid, options = {}) {
+        const { gateways } = options;
+        try {
+          return await this._client.warmGateways(cid, { gateways });
+        } catch (error) {
+          return { warmed: [] };
+        }
+      }
+      /**
+       * Clear cache
+       */
+      clearCache() {
+        this._cache.clear();
+      }
+      /**
+       * Get cache statistics
+       * @returns {object} - Cache stats
+       */
+      getCacheStats() {
+        return this._cache.stats();
+      }
+      // Private methods
+      /**
+       * Fetch from multiple gateways in parallel
+       * @param {string[]} urls - Gateway URLs to try
+       * @param {number} timeout - Timeout per gateway in ms
+       * @returns {Promise<any|null>} - First successful result or null
+       * @private
+       */
+      async _parallelFetch(urls, timeout) {
+        if (!urls || urls.length === 0) {
+          return null;
+        }
+        const fetchOne = async (url) => {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), timeout);
+          try {
+            const response = await fetch(url, {
+              signal: controller.signal,
+              headers: { Accept: "application/json" }
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+              return null;
+            }
+            const text = await response.text();
+            try {
+              return JSON.parse(text);
+            } catch {
+              return text;
+            }
+          } catch (error) {
+            clearTimeout(timeoutId);
+            return null;
+          }
+        };
+        const results = await Promise.allSettled(urls.map((url) => fetchOne(url)));
+        for (const result of results) {
+          if (result.status === "fulfilled" && result.value !== null) {
+            return result.value;
+          }
+        }
+        return null;
+      }
+    };
+    module2.exports = { IPFSService };
+  }
+});
+
+// src/hooks/useSubDAOs.js
+var require_useSubDAOs = __commonJS({
+  "src/hooks/useSubDAOs.js"(exports2, module2) {
+    var useSWR = require("swr");
+    function useSubDAOs(subgraphService, options = {}) {
+      const {
+        limit = 50,
+        skip = 0,
+        cache = true,
+        refreshInterval,
+        revalidateOnFocus = true,
+        revalidateOnReconnect = true
+      } = options;
+      const cacheKey = subgraphService ? ["subdaos", subgraphService.url, limit, skip] : null;
+      const fetcher = async () => {
+        if (!subgraphService) {
+          throw new Error("SubgraphService is required");
+        }
+        return await subgraphService.getSubDAOs({ limit, skip, cache });
+      };
+      return useSWR(cacheKey, fetcher, {
+        refreshInterval,
+        revalidateOnFocus,
+        revalidateOnReconnect,
+        dedupingInterval: cache ? 3e4 : 0
+        // Match service cache TTL
+      });
+    }
+    module2.exports = { useSubDAOs };
+  }
+});
+
+// src/hooks/useProposals.js
+var require_useProposals = __commonJS({
+  "src/hooks/useProposals.js"(exports2, module2) {
+    var useSWR = require("swr");
+    function useProposals(subgraphService, options = {}) {
+      const {
+        governor,
+        subdao,
+        states,
+        fromTimestamp,
+        toTimestamp,
+        limit = 20,
+        skip = 0,
+        cache = true,
+        refreshInterval,
+        revalidateOnFocus = true,
+        revalidateOnReconnect = true
+      } = options;
+      const cacheKey = subgraphService ? [
+        "proposals",
+        subgraphService.url,
+        governor,
+        subdao,
+        states?.join(","),
+        fromTimestamp,
+        toTimestamp,
+        limit,
+        skip
+      ] : null;
+      const fetcher = async () => {
+        if (!subgraphService) {
+          throw new Error("SubgraphService is required");
+        }
+        return await subgraphService.getProposals({
+          governor,
+          subdao,
+          states,
+          fromTimestamp,
+          toTimestamp,
+          limit,
+          skip,
+          cache
+        });
+      };
+      return useSWR(cacheKey, fetcher, {
+        refreshInterval,
+        revalidateOnFocus,
+        revalidateOnReconnect,
+        dedupingInterval: cache ? 3e4 : 0
+        // Match service cache TTL
+      });
+    }
+    module2.exports = { useProposals };
+  }
+});
+
+// src/hooks/useFetchCID.js
+var require_useFetchCID = __commonJS({
+  "src/hooks/useFetchCID.js"(exports2, module2) {
+    var useSWR = require("swr");
+    function useFetchCID(ipfsService, cid, options = {}) {
+      const {
+        cache = true,
+        timeout = 5e3,
+        extraGateways = [],
+        refreshInterval,
+        revalidateOnFocus = false,
+        // CIDs are immutable
+        revalidateOnReconnect = false
+        // CIDs are immutable
+      } = options;
+      const cacheKey = ipfsService && cid ? ["ipfs-cid", cid] : null;
+      const fetcher = async () => {
+        if (!ipfsService) {
+          throw new Error("IPFSService is required");
+        }
+        if (!cid) {
+          throw new Error("CID is required");
+        }
+        return await ipfsService.fetchByCID(cid, {
+          cache,
+          timeout,
+          extraGateways
+        });
+      };
+      return useSWR(cacheKey, fetcher, {
+        refreshInterval,
+        revalidateOnFocus,
+        revalidateOnReconnect,
+        dedupingInterval: cache ? 3e5 : 0,
+        // Match service cache TTL (5min)
+        // CIDs are immutable, so we can cache errors too
+        shouldRetryOnError: true,
+        errorRetryInterval: 5e3,
+        errorRetryCount: 3
+      });
+    }
+    module2.exports = { useFetchCID };
+  }
+});
+
+// src/hooks/useUpload.js
+var require_useUpload = __commonJS({
+  "src/hooks/useUpload.js"(exports2, module2) {
+    var { useState, useCallback } = require("react");
+    function useUpload(ipfsService) {
+      const [isUploading, setIsUploading] = useState(false);
+      const [error, setError] = useState(null);
+      const [data, setData] = useState(null);
+      const upload = useCallback(
+        async (content, options = {}) => {
+          if (!ipfsService) {
+            const err = new Error("IPFSService is required");
+            setError(err);
+            throw err;
+          }
+          setIsUploading(true);
+          setError(null);
+          try {
+            const cid = await ipfsService.upload(content, options);
+            setData(cid);
+            return cid;
+          } catch (err) {
+            setError(err);
+            throw err;
+          } finally {
+            setIsUploading(false);
+          }
+        },
+        [ipfsService]
+      );
+      const reset = useCallback(() => {
+        setIsUploading(false);
+        setError(null);
+        setData(null);
+      }, []);
+      return {
+        upload,
+        isUploading,
+        error,
+        data,
+        reset
+      };
+    }
+    module2.exports = { useUpload };
+  }
+});
+
+// src/hooks/index.js
+var require_hooks = __commonJS({
+  "src/hooks/index.js"(exports2, module2) {
+    var { useSubDAOs } = require_useSubDAOs();
+    var { useProposals } = require_useProposals();
+    var { useFetchCID } = require_useFetchCID();
+    var { useUpload } = require_useUpload();
+    module2.exports = {
+      useSubDAOs,
+      useProposals,
+      useFetchCID,
+      useUpload
+    };
+  }
+});
+
 // src/index.js
 var require_src = __commonJS({
   "src/index.js"(exports2, module2) {
@@ -8127,6 +9109,16 @@ var require_src = __commonJS({
         openzeppelin: require_openzeppelin()
       }
     };
+    var { SubgraphService } = require_client();
+    var { IPFSService } = require_client2();
+    var serviceErrors = require_errors2();
+    var { SimpleCache } = require_cache();
+    var { retryWithBackoff } = require_retry();
+    var hooks = null;
+    try {
+      hooks = require_hooks();
+    } catch (err) {
+    }
     module2.exports = {
       version: pkg.version,
       getProvider: utils.getProvider,
@@ -8157,6 +9149,18 @@ var require_src = __commonJS({
       errors,
       doppler,
       adapters,
+      // New service layer exports
+      services: {
+        SubgraphService,
+        IPFSService
+      },
+      serviceErrors,
+      serviceUtils: {
+        SimpleCache,
+        retryWithBackoff
+      },
+      // React hooks (optional - requires react + swr peer dependencies)
+      hooks,
       // Legacy exports (deprecated): maintain compatibility while consumers migrate
       resolveGovernanceContext: async function legacyResolveGovernanceContext(args) {
         console.warn("[@sage-protocol/sdk] resolveGovernanceContext is deprecated. Use governance helpers instead.");