@obscura-fhe/sdk 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `@obscura-fhe/sdk` are documented in this file.
 
+## [1.0.2] - 2026-05-30
+
+### Added
+
+- **Credit module:** `getMarketUtilization()` — public pool aggregates (`utilizationBps`, `totalSupplyAssets`, `totalBorrowAssets`)
+- **Credit module:** `getPositionHandles()` — encrypted position handles as opaque hex; optional plaintext shadows with explicit warning
+- Exported types: `CreditMarketUtilization`, `CreditPositionHandles`
+
+## [1.0.1] - 2026-05-29
+
+### Fixed
+
+- **Vote module:** `getProposalCount()` now reads on-chain `nextProposalId()` instead of non-existent `proposalCount()` (verified against Arbitrum Sepolia ObscuraVote `0xe358…1730`)
+
+### Added
+
+- `ActivityModule.isConfigured()` — check Supabase credentials before querying
+- Clearer activity error messages with default Supabase URL and setup instructions
+- Module examples: `reputation`, `activity`, `notifications`, `pay`, `credit`, `vote`
+- README: requirements matrix, viem rpcUrl/transport examples, TypeScript `verbatimModuleSyntax` guidance
+
+### Docs
+
+- Developer portal quick-start, SDK onboarding, and SDK reference updated with hidden requirements
+
 ## [1.0.0] - 2026-05-29
 
 ### Added

package/README.md

@@ -1,8 +1,8 @@
 # @obscura-fhe/sdk
 
-Official TypeScript SDK for **Obscura Pay**, **Credit**, and Vote on Arbitrum Sepolia.
+Official TypeScript SDK for **Obscura Pay**, **Credit**, and **Vote** on Arbitrum Sepolia.
 
-Privacy-first DeFi with FHE (Fully Homomorphic Encryption). Framework-agnostic — works in Node.js, browsers, and automation scripts.
+Privacy-first DeFi with FHE (Fully Homomorphic Encryption). Framework-agnostic — works in Node.js, browsers, Vite, Next.js, and automation scripts.
 
 ## Install
 
@@ -10,7 +10,22 @@ Privacy-first DeFi with FHE (Fully Homomorphic Encryption). Framework-agnostic
 npm install @obscura-fhe/sdk viem
 ```
 
-`viem` is a peer dependency (v2+).
+`viem` is a **peer dependency** (v2+). You must install it alongside the SDK.
+
+## Requirements at a glance
+
+| Module | Wallet | RPC / chain | Supabase | FHE provider |
+|--------|--------|-------------|----------|--------------|
+| `reputation` | No | No | No | No |
+| `notifications` | No | No | No | No |
+| `activity` | No | No | **Yes** (URL + anon key) | No |
+| `pay` / `credit` / `vote` reads | No | **Yes** (default RPC) | No | No |
+| Encrypted writes (`buildShield`, etc.) | Optional* | Yes | No | **Yes** (or pre-encrypted input) |
+| `sendCall()` | **Yes** (`walletClient`) | Yes | No | If write needs FHE |
+
+\*Use `encodeCall()` and sign externally if you do not inject `walletClient`.
+
+**Network:** Arbitrum Sepolia (`chainId` **421614**) by default.
 
 ## Quick start
 
@@ -18,49 +33,153 @@ npm install @obscura-fhe/sdk viem
 import { ObscuraSDK } from "@obscura-fhe/sdk";
 
 const sdk = ObscuraSDK.create({
-  supabaseAnonKey: process.env.OBSCURA_SUPABASE_ANON_KEY, // required for activity feed
+  // Required for activity feed only:
+  supabaseAnonKey: process.env.OBSCURA_SUPABASE_ANON_KEY,
+  // supabaseUrl defaults to Obscura production project
 });
 
-// Reputation (off-chain, obscura-api)
+// Reputation — no wallet, no Supabase
 const summary = await sdk.reputation.getSummary("0xYourWallet...");
 console.log(summary.tier, summary.totalCappedWeight);
 
-// Activity feed (Supabase)
-const { items, hasMore } = await sdk.activity.listForWallet("0xYourWallet...", {
-  filter: "credit",
+// Activity — requires supabaseAnonKey
+if (sdk.activity.isConfigured()) {
+  const { items } = await sdk.activity.listForWallet("0xYourWallet...", { filter: "credit" });
+  console.log(items.length);
+}
+
+// On-chain read — uses default Arbitrum Sepolia RPC
+const proposalCount = await sdk.vote.getProposalCount(); // reads nextProposalId()
+const balanceCt = await sdk.pay.getShieldedBalance("0xYourWallet...");
+```
+
+## viem integration (recommended)
+
+Pass an explicit RPC URL and viem clients when you need custom transport, account abstraction, or `sendCall()`:
+
+```typescript
+import { ObscuraSDK } from "@obscura-fhe/sdk";
+import { createPublicClient, createWalletClient, http, custom } from "viem";
+import { arbitrumSepolia } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+
+const rpcUrl = process.env.ARB_SEPOLIA_RPC_URL ?? "https://sepolia-rollup.arbitrum.io/rpc";
+
+const publicClient = createPublicClient({
+  chain: arbitrumSepolia,
+  transport: http(rpcUrl),
+});
+
+// Browser wallet (MetaMask, etc.)
+const walletClient = createWalletClient({
+  chain: arbitrumSepolia,
+  transport: custom(window.ethereum),
+});
+
+// Or Node with private key
+// const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+// const walletClient = createWalletClient({ account, chain: arbitrumSepolia, transport: http(rpcUrl) });
+
+const sdk = ObscuraSDK.create({
+  chainId: 421614,
+  rpcUrl,
+  publicClient,
+  walletClient,
+  supabaseUrl: process.env.OBSCURA_SUPABASE_URL,
+  supabaseAnonKey: process.env.OBSCURA_SUPABASE_ANON_KEY,
+});
+
+// Shorthand — SDK creates publicClient from rpcUrl when publicClient omitted:
+const sdkMinimal = ObscuraSDK.create({ rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc" });
+```
+
+## Activity module — Supabase setup
+
+The activity feed reads indexed on-chain events from Supabase (`obscura_activity`). **Both** credentials are required:
+
+```typescript
+import { ObscuraSDK, DEFAULT_SUPABASE_URL } from "@obscura-fhe/sdk";
+
+const sdk = ObscuraSDK.create({
+  supabaseUrl: process.env.OBSCURA_SUPABASE_URL ?? DEFAULT_SUPABASE_URL,
+  supabaseAnonKey: process.env.OBSCURA_SUPABASE_ANON_KEY!, // required
+});
+
+if (!sdk.activity.isConfigured()) {
+  throw new Error("Set OBSCURA_SUPABASE_ANON_KEY for activity queries");
+}
+
+const { items, hasMore } = await sdk.activity.listForWallet(wallet, {
+  filter: "vote", // all | pay | credit | vote | stream | ...
   page: 0,
+  pageSize: 20,
 });
+```
 
-// Notifications
-const vapidKey = await sdk.notifications.getVapidPublicKey();
-const prefs = await sdk.notifications.getPrefs("0xYourWallet...");
+**Environment variables:**
 
-// On-chain reads
-const balanceCtHash = await sdk.pay.getShieldedBalance("0xYourWallet...");
-const proposalCount = await sdk.vote.getProposalCount();
+```bash
+OBSCURA_SUPABASE_URL=https://quoovjkjwgtdqwdofubh.supabase.co   # optional — this is the default
+OBSCURA_SUPABASE_ANON_KEY=eyJ...                                 # required for activity
+```
+
+Get the anon key from Supabase → Project Settings → API → `anon` `public` key.
+
+## TypeScript setup
+
+The SDK ships ESM + CJS with `.d.ts` types. Recommended `tsconfig.json`:
 
-// Transaction builders (return ContractCall — sign with your wallet)
-const call = await sdk.pay.buildTransfer(to, amount, encryptedAmount);
-const calldata = sdk.encodeCall(call);
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true
+  }
+}
 ```
 
-## Modules
+### `verbatimModuleSyntax`
 
-| Module | Methods | Backend |
-|--------|---------|---------|
-| `pay` | `getShieldedBalance`, `buildShield`, `buildUnshield`, `buildTransfer` | On-chain (ocUSDC_Pay) |
-| `credit` | `getMarketAddress`, `buildSupplyCollateral`, `buildBorrow`, `buildRepay` | On-chain (credit market) |
-| `vote` | `getProposalCount`, `getProposal`, `buildCastVote`, `buildDelegate` | On-chain (ObscuraVote) |
-| `reputation` | `getSummary` | obscura-api REST |
-| `activity` | `listForWallet`, `getEventFilters` | Supabase |
-| `notifications` | `getVapidPublicKey`, `getPrefs`, `savePrefs`, `subscribe`, `unsubscribe` | obscura-api REST |
+With `verbatimModuleSyntax: true`, TypeScript requires **type-only imports** for types:
+
+```typescript
+// Correct
+import { ObscuraSDK } from "@obscura-fhe/sdk";
+import type { FheProvider, ReputationSummary, ContractCall } from "@obscura-fhe/sdk";
+
+// Wrong — TS1363 error under verbatimModuleSyntax
+import { FheProvider, ReputationSummary } from "@obscura-fhe/sdk";
+```
+
+If you cannot use type-only imports, set `"verbatimModuleSyntax": false` or use `"isolatedModules": true` without verbatim (Vite/Next default).
+
+## Module examples
+
+See [`examples/`](./examples/) for runnable scripts:
 
-## Configuration
+| File | Module |
+|------|--------|
+| `examples/reputation.ts` | Reputation summary |
+| `examples/activity.ts` | Activity feed (Supabase) |
+| `examples/notifications.ts` | VAPID + prefs |
+| `examples/pay.ts` | Shielded balance + transfer builder |
+| `examples/credit.ts` | Market address + borrow builder |
+| `examples/vote.ts` | Proposal count + delegate |
+| `examples/basic-usage.ts` | Combined smoke test |
+
+Run: `npm run example:basic` or `npx tsx examples/reputation.ts`
+
+## Configuration reference
 
 ```typescript
 ObscuraSDK.create({
   chainId: 421614,                    // default: Arbitrum Sepolia
-  rpcUrl: "https://...",              // default: Arbitrum Sepolia RPC
+  rpcUrl: "https://...",              // default: Arbitrum Sepolia public RPC
   apiUrl: "https://...",              // default: obscura-api production
   supabaseUrl: "https://...",         // default: Obscura Supabase project
   supabaseAnonKey: "...",             // required for activity module
@@ -73,14 +192,14 @@ ObscuraSDK.create({
 
 ## FHE (encrypted writes)
 
-Encrypted contract inputs require a host-supplied `FheProvider` (typically wrapping `@cofhe/sdk`):
+Encrypted contract inputs require a host-supplied `FheProvider` (typically wrapping `@fhenixprotocol/cofhe-sdk`):
 
 ```typescript
 import type { FheProvider } from "@obscura-fhe/sdk";
 
 const fhe: FheProvider = {
   async encryptUint64(value, { contractAddress }) {
-    // wrap @cofhe/sdk encrypt here
+    // wrap CoFHE encrypt — user-triggered only
     return { ctHash, securityZone, utype, signature };
   },
 };
@@ -99,11 +218,24 @@ const call = sdk.vote.buildDelegate("0xDelegatee...");
 const hash = await sdk.sendCall(call, account); // requires walletClient
 ```
 
+## Modules
+
+| Module | Methods | Backend |
+|--------|---------|---------|
+| `pay` | `getShieldedBalance`, `buildShield`, `buildUnshield`, `buildTransfer` | On-chain (ocUSDC_Pay) |
+| `credit` | `getMarketAddress`, `buildSupplyCollateral`, `buildBorrow`, `buildRepay` | On-chain (credit market) |
+| `vote` | `getProposalCount`, `getProposal`, `buildCastVote`, `buildDelegate` | On-chain (ObscuraVote) |
+| `reputation` | `getSummary` | obscura-api REST |
+| `activity` | `listForWallet`, `getEventFilters`, `isConfigured` | Supabase |
+| `notifications` | `getVapidPublicKey`, `getPrefs`, `savePrefs`, `subscribe`, `unsubscribe` | obscura-api REST |
+
 ## Defaults (Arbitrum Sepolia)
 
 | Setting | Value |
 |---------|-------|
 | Chain ID | `421614` |
+| RPC | `https://sepolia-rollup.arbitrum.io/rpc` |
+| Supabase URL | `https://quoovjkjwgtdqwdofubh.supabase.co` |
 | ocUSDC_Pay | `0xEd46020Df8abe7BB1E096f27d089F4326D223a53` |
 | Vote | `0xe358776AfdbA95d7c9F040e6ef1f5A021aF91730` |
 | Credit market | `0x1Ec113297c7F9516A6604aa3b18C180559a6f551` |
@@ -115,7 +247,7 @@ Core: `ObscuraSDK`, `ObscuraSDKConfig`, `ContractCall`, `InEuint64`, `FheProvide
 
 Types: `ReputationSummary`, `ActivityItem`, `NotificationPrefs`, `ProposalState`, …
 
-Constants: `DEFAULT_ADDRESSES`, `ARBITRUM_SEPOLIA_CHAIN_ID`, `ACTIVITY_EVENT_FILTERS`
+Constants: `DEFAULT_ADDRESSES`, `DEFAULT_SUPABASE_URL`, `ARBITRUM_SEPOLIA_CHAIN_ID`, `ACTIVITY_EVENT_FILTERS`
 
 Utilities: `encodeCall`, `normalizeWallet`, `toContractInEuint64`, `HttpError`
 

package/dist/index.cjs

@@ -222,16 +222,30 @@ var ACTIVITY_EVENT_FILTERS = {
 var DEFAULT_PAGE_SIZE = 20;
 var ActivityModule = class {
   client;
+  supabaseUrl;
+  supabaseAnonKey;
   constructor(supabaseUrl, supabaseAnonKey) {
+    this.supabaseUrl = supabaseUrl;
+    this.supabaseAnonKey = supabaseAnonKey;
     this.client = supabaseUrl && supabaseAnonKey ? supabaseJs.createClient(supabaseUrl, supabaseAnonKey) : null;
   }
+  /** True when both Supabase URL and anon key were supplied at SDK init. */
+  isConfigured() {
+    return this.client !== null;
+  }
   getEventFilters() {
     return ACTIVITY_EVENT_FILTERS;
   }
   async listForWallet(wallet, options = {}) {
     if (!this.client) {
       throw new Error(
-        "Supabase not configured. Pass supabaseUrl and supabaseAnonKey to ObscuraSDK.create()."
+        [
+          "Activity module requires Supabase credentials.",
+          `Pass supabaseAnonKey (and optionally supabaseUrl) to ObscuraSDK.create().`,
+          `Default URL: ${DEFAULT_SUPABASE_URL}`,
+          "Get the anon key from your Supabase project \u2192 Settings \u2192 API \u2192 anon public.",
+          "Reputation and notifications work without Supabase; activity does not."
+        ].join(" ")
       );
     }
     const normalized = normalizeWallet(wallet);
@@ -303,6 +317,53 @@ var OC_USDC_PAY_ABI = [
   }
 ];
 var CREDIT_MARKET_ABI = [
+  {
+    name: "utilizationBps",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "totalSupplyAssets",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint128" }]
+  },
+  {
+    name: "totalBorrowAssets",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint128" }]
+  },
+  {
+    name: "getPosition",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }],
+    outputs: [
+      { name: "encSupplyShares", type: "uint256" },
+      { name: "borrowShares", type: "uint256" },
+      { name: "collateral", type: "uint256" },
+      { name: "disburseTo", type: "uint256" }
+    ]
+  },
+  {
+    name: "getPlainCollateral",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }],
+    outputs: [{ name: "", type: "uint128" }]
+  },
+  {
+    name: "getPlainBorrow",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }],
+    outputs: [{ name: "", type: "uint128" }]
+  },
   {
     name: "supplyCollateral",
     type: "function",
@@ -333,7 +394,7 @@ var CREDIT_MARKET_ABI = [
 ];
 var OBSCURA_VOTE_ABI = [
   {
-    name: "proposalCount",
+    name: "nextProposalId",
     type: "function",
     stateMutability: "view",
     inputs: [],
@@ -375,6 +436,11 @@ var OBSCURA_VOTE_ABI = [
 ];
 
 // src/modules/credit.ts
+var PLAINTEXT_SHADOW_WARNING = "Plaintext shadows are public testnet UI hints only \u2014 not encrypted balances. Do not treat as private position size. Omit on mainnet strict privacy mode.";
+function bigintToHandleHex(value) {
+  const hex = value.toString(16).padStart(64, "0");
+  return `0x${hex}`;
+}
 var CreditModule = class {
   constructor(deps) {
     this.deps = deps;
@@ -383,6 +449,75 @@ var CreditModule = class {
   getMarketAddress(override) {
     return override ?? this.deps.addresses.CreditCanonicalPayOcUSDCMarket;
   }
+  /** Public pool aggregates — no wallet required */
+  async getMarketUtilization(marketAddress) {
+    const market = this.getMarketAddress(marketAddress);
+    const [utilizationBps, totalSupplyAssets, totalBorrowAssets] = await Promise.all([
+      this.deps.publicClient.readContract({
+        address: market,
+        abi: CREDIT_MARKET_ABI,
+        functionName: "utilizationBps"
+      }),
+      this.deps.publicClient.readContract({
+        address: market,
+        abi: CREDIT_MARKET_ABI,
+        functionName: "totalSupplyAssets"
+      }),
+      this.deps.publicClient.readContract({
+        address: market,
+        abi: CREDIT_MARKET_ABI,
+        functionName: "totalBorrowAssets"
+      })
+    ]);
+    return {
+      marketAddress: market,
+      utilizationBps,
+      totalSupplyAssets,
+      totalBorrowAssets
+    };
+  }
+  /**
+   * Returns encrypted position handles as opaque hex strings.
+   * Plaintext shadows are optional and labeled with an explicit warning.
+   */
+  async getPositionHandles(wallet, options = {}) {
+    const normalized = normalizeWallet(wallet);
+    if (!normalized) throw new Error("Invalid wallet address");
+    const market = this.getMarketAddress(options.marketAddress);
+    const position = await this.deps.publicClient.readContract({
+      address: market,
+      abi: CREDIT_MARKET_ABI,
+      functionName: "getPosition",
+      args: [normalized]
+    });
+    const result = {
+      marketAddress: market,
+      wallet: normalized,
+      encryptedSupplySharesHandle: bigintToHandleHex(position[0]),
+      encryptedBorrowSharesHandle: bigintToHandleHex(position[1]),
+      encryptedCollateralHandle: bigintToHandleHex(position[2])
+    };
+    if (options.includePlaintextShadows) {
+      const [plainCollateral, plainBorrow] = await Promise.all([
+        this.deps.publicClient.readContract({
+          address: market,
+          abi: CREDIT_MARKET_ABI,
+          functionName: "getPlainCollateral",
+          args: [normalized]
+        }),
+        this.deps.publicClient.readContract({
+          address: market,
+          abi: CREDIT_MARKET_ABI,
+          functionName: "getPlainBorrow",
+          args: [normalized]
+        })
+      ]);
+      result.plaintextShadowWarning = PLAINTEXT_SHADOW_WARNING;
+      result.plainCollateral = plainCollateral;
+      result.plainBorrow = plainBorrow;
+    }
+    return result;
+  }
   async buildSupplyCollateral(amount, encryptedAmount, marketAddress) {
     const market = this.getMarketAddress(marketAddress);
     const enc = await resolveInEuint64(amount, market, this.deps.fhe, encryptedAmount);
@@ -536,11 +671,12 @@ var VoteModule = class {
   get voteAddress() {
     return this.deps.addresses.ObscuraVote;
   }
+  /** Returns total proposals created (= public `nextProposalId` on ObscuraVote). */
   async getProposalCount() {
     return this.deps.publicClient.readContract({
       address: this.deps.addresses.ObscuraVote,
       abi: OBSCURA_VOTE_ABI,
-      functionName: "proposalCount"
+      functionName: "nextProposalId"
     });
   }
   async getProposal(id) {
@@ -620,6 +756,7 @@ var ObscuraSDK = class _ObscuraSDK {
     this.credit = new CreditModule({
       chainId: this.chainId,
       addresses: this.addresses,
+      publicClient: this.publicClient,
       fhe: this.fhe
     });
     this.vote = new VoteModule(moduleDeps);