feat: allow read-only operations with wallet addr (#284)

* feat: allow read-only operations with wallet addr

* chore: fix lint

* fix: track authMode for synapse instance

* test: mocks recognize read-only mode

Author: SgtPooki

src/core/synapse/index.ts

@@ -19,11 +19,13 @@ import { getTelemetryConfig } from './telemetry-config.js'
 export * from './constants.js'
 
 const WEBSOCKET_REGEX = /^ws(s)?:\/\//i
+const AUTH_MODE_SYMBOL = Symbol.for('filecoin-pin.authMode')
 
 let synapseInstance: Synapse | null = null
 let storageInstance: StorageContext | null = null
 let currentProviderInfo: ProviderInfo | null = null
 let activeProvider: any = null // Track the provider for cleanup
+type AuthMode = 'standard' | 'session-key' | 'read-only' | 'signer'
 
 /**
  * Complete application configuration interface
@@ -49,6 +51,8 @@ interface BaseSynapseConfig extends Omit<SynapseOptions, 'withCDN' | 'warmStorag
   rpcUrl?: string | undefined
   /** Optional override for WarmStorage contract address */
   warmStorageAddress?: string | undefined
+  /** Optional flag for read-only auth (address-only signer) */
+  readOnly?: boolean | undefined
   withCDN?: boolean | undefined
   /** Default metadata to apply when creating or reusing datasets */
   dataSetMetadata?: Record<string, string>
@@ -83,6 +87,16 @@ export interface SessionKeyConfig extends BaseSynapseConfig {
   sessionKey: string
 }
 
+/**
+ * Read-only authentication using an address-only signer
+ *
+ * This supports querying balances and status without signing transactions.
+ */
+export interface ReadOnlyConfig extends BaseSynapseConfig {
+  walletAddress: string
+  readOnly: true
+}
+
 /**
  * Signer-based authentication with ethers Signer
  */
@@ -100,7 +114,7 @@ export interface SignerConfig extends BaseSynapseConfig {
  * 2. Session Key: walletAddress + sessionKey
  * 3. Signer: ethers Signer instance
  */
-export type SynapseSetupConfig = PrivateKeyConfig | SessionKeyConfig | SignerConfig
+export type SynapseSetupConfig = PrivateKeyConfig | SessionKeyConfig | ReadOnlyConfig | SignerConfig
 
 /**
  * Structured service object containing the fully initialized Synapse SDK and
@@ -190,6 +204,18 @@ export function resetSynapseService(): void {
   activeProvider = null
 }
 
+function setAuthMode(synapse: Synapse, mode: AuthMode): void {
+  ;(synapse as any)[AUTH_MODE_SYMBOL] = mode
+}
+
+export function isViewOnlyMode(synapse: Synapse): boolean {
+  try {
+    return (synapse as any)[AUTH_MODE_SYMBOL] === 'read-only'
+  } catch {
+    return false
+  }
+}
+
 /**
  * Check if Synapse is using session key authentication
  *
@@ -203,6 +229,10 @@ export function resetSynapseService(): void {
  */
 export function isSessionKeyMode(synapse: Synapse): boolean {
   try {
+    const markedMode = (synapse as any)[AUTH_MODE_SYMBOL]
+    if (markedMode === 'session-key') return true
+    if (markedMode === 'read-only') return false
+
     const client = synapse.getClient()
 
     // The client might be wrapped in a NonceManager, check the underlying signer
@@ -231,30 +261,40 @@ function isSessionKeyConfig(config: Partial<SynapseSetupConfig>): config is Sess
   )
 }
 
+function isReadOnlyConfig(config: Partial<SynapseSetupConfig>): config is ReadOnlyConfig {
+  return config.readOnly === true && 'walletAddress' in config && config.walletAddress != null
+}
+
 function isSignerConfig(config: Partial<SynapseSetupConfig>): config is SignerConfig {
   return 'signer' in config && config.signer != null
 }
 
 /**
  * Validate authentication configuration
  */
-function validateAuthConfig(config: Partial<SynapseSetupConfig>): 'standard' | 'session-key' | 'signer' {
+function validateAuthConfig(config: Partial<SynapseSetupConfig>): 'standard' | 'session-key' | 'read-only' | 'signer' {
   const hasPrivateKey = isPrivateKeyConfig(config)
   const hasSessionKey = isSessionKeyConfig(config)
+  const hasReadOnly = isReadOnlyConfig(config)
   const hasSigner = isSignerConfig(config)
 
-  const authCount = [hasPrivateKey, hasSessionKey, hasSigner].filter(Boolean).length
+  const authCount = [hasPrivateKey, hasSessionKey, hasReadOnly, hasSigner].filter(Boolean).length
 
   if (authCount === 0) {
-    throw new Error('Authentication required: provide either privateKey, walletAddress + sessionKey, or signer')
+    throw new Error(
+      'Authentication required: provide either privateKey, walletAddress + sessionKey, view-address, or signer'
+    )
   }
 
   if (authCount > 1) {
-    throw new Error('Conflicting authentication: provide only one of privateKey, walletAddress + sessionKey, or signer')
+    throw new Error(
+      'Conflicting authentication: provide only one of privateKey, walletAddress + sessionKey, view-address, or signer'
+    )
   }
 
   if (hasPrivateKey) return 'standard'
   if (hasSessionKey) return 'session-key'
+  if (hasReadOnly) return 'read-only'
   return 'signer'
 }
 
@@ -382,6 +422,23 @@ export async function initializeSynapse(config: Partial<SynapseSetupConfig>, log
         signer: ownerSigner,
       })
       await setupSessionKey(synapse, sessionWallet, logger)
+      setAuthMode(synapse, 'session-key')
+    } else if (authMode === 'read-only') {
+      // Read-only mode - type guard ensures walletAddress is defined
+      if (!isReadOnlyConfig(config)) {
+        throw new Error('Internal error: read-only mode but config type mismatch')
+      }
+
+      const provider = createProvider(rpcURL)
+      activeProvider = provider
+
+      const readOnlySigner = new AddressOnlySigner(config.walletAddress, provider)
+
+      synapse = await Synapse.create({
+        ...synapseOptions,
+        signer: readOnlySigner,
+      })
+      setAuthMode(synapse, 'read-only')
     } else if (authMode === 'signer') {
       // Signer mode - type guard ensures signer is defined
       if (!isSignerConfig(config)) {
@@ -390,6 +447,7 @@ export async function initializeSynapse(config: Partial<SynapseSetupConfig>, log
 
       synapse = await Synapse.create({ ...synapseOptions, signer: config.signer })
       activeProvider = synapse.getProvider()
+      setAuthMode(synapse, 'signer')
     } else {
       // Private key mode - type guard ensures privateKey is defined
       if (!isPrivateKeyConfig(config)) {
@@ -398,6 +456,7 @@ export async function initializeSynapse(config: Partial<SynapseSetupConfig>, log
 
       synapse = await Synapse.create({ ...synapseOptions, privateKey: config.privateKey })
       activeProvider = synapse.getProvider()
+      setAuthMode(synapse, 'standard')
     }
 
     const network = synapse.getNetwork()

src/index-types.ts

@@ -36,6 +36,7 @@ export type {
   CreateStorageContextOptions,
   DatasetOptions,
   PrivateKeyConfig,
+  ReadOnlyConfig,
   SessionKeyConfig,
   SignerConfig,
   SynapseService,

src/test/unit/add.test.ts

@@ -37,9 +37,12 @@ vi.mock('../../core/synapse/index.js', () => ({
     // Validate auth config (mirrors validateAuthConfig in actual code)
     const hasStandardAuth = config.privateKey != null
     const hasSessionKeyAuth = config.walletAddress != null && config.sessionKey != null
+    const hasViewOnlyAuth = config.readOnly === true && config.walletAddress != null
 
-    if (!hasStandardAuth && !hasSessionKeyAuth) {
-      throw new Error('Authentication required: provide either a privateKey or walletAddress + sessionKey')
+    if (!hasStandardAuth && !hasSessionKeyAuth && !hasViewOnlyAuth) {
+      throw new Error(
+        'Authentication required: provide either privateKey, walletAddress + sessionKey, view-address, or signer'
+      )
     }
 
     return {

src/test/unit/data-set.test.ts

@@ -82,9 +82,12 @@ const {
     // Validate auth like the real initializeSynapse does
     const hasStandardAuth = config.privateKey != null
     const hasSessionKeyAuth = config.walletAddress != null && config.sessionKey != null
+    const hasViewOnlyAuth = config.readOnly === true && config.walletAddress != null
 
-    if (!hasStandardAuth && !hasSessionKeyAuth) {
-      throw new Error('Authentication required: provide either a privateKey or walletAddress + sessionKey')
+    if (!hasStandardAuth && !hasSessionKeyAuth && !hasViewOnlyAuth) {
+      throw new Error(
+        'Authentication required: provide either privateKey, walletAddress + sessionKey, view-address, or signer'
+      )
     }
 
     return {

src/test/unit/import.test.ts

@@ -110,9 +110,12 @@ vi.mock('../../core/synapse/index.js', async () => {
       // Validate auth config (mirrors validateAuthConfig in actual code)
       const hasStandardAuth = config.privateKey != null
       const hasSessionKeyAuth = config.walletAddress != null && config.sessionKey != null
+      const hasViewOnlyAuth = config.readOnly === true && config.walletAddress != null
 
-      if (!hasStandardAuth && !hasSessionKeyAuth) {
-        throw new Error('Authentication required: provide either a privateKey or walletAddress + sessionKey')
+      if (!hasStandardAuth && !hasSessionKeyAuth && !hasViewOnlyAuth) {
+        throw new Error(
+          'Authentication required: provide either privateKey, walletAddress + sessionKey, view-address, or signer'
+        )
       }
 
       const mockSynapse = new MockSynapse()

src/test/unit/synapse-service.test.ts

@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createConfig } from '../../config.js'
 import {
   getSynapseService,
+  initializeSynapse,
   resetSynapseService,
   type SynapseSetupConfig,
   setupSynapse,
@@ -79,6 +80,28 @@ describe('synapse-service', () => {
       )
     })
 
+    it('should initialize Synapse in read-only mode when requested', async () => {
+      const readOnlyConfig: SynapseSetupConfig = {
+        walletAddress: '0x0000000000000000000000000000000000000002',
+        readOnly: true,
+        rpcUrl: 'wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1',
+      }
+
+      const infoSpy = vi.spyOn(logger, 'info')
+
+      const synapse = await initializeSynapse(readOnlyConfig, logger)
+
+      expect(synapse).toBeDefined()
+      expect(infoSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: 'synapse.init',
+          authMode: 'read-only',
+          rpcUrl: readOnlyConfig.rpcUrl,
+        }),
+        'Initializing Synapse SDK'
+      )
+    })
+
     it('should call provider selection callback', async () => {
       const callbacks: any[] = []
       const originalCreate = synapseSdk.Synapse.create

src/utils/cli-auth.ts

@@ -23,6 +23,8 @@ export interface CLIAuthOptions {
   walletAddress?: string | undefined
   /** Session key private key */
   sessionKey?: string | undefined
+  /** View-only wallet address (no signing) */
+  viewAddress?: string | undefined
   /** Filecoin network: mainnet or calibration */
   network?: string | undefined
   /** RPC endpoint URL (overrides network if specified) */
@@ -51,6 +53,7 @@ export function parseCLIAuth(options: CLIAuthOptions): Partial<SynapseSetupConfi
   const privateKey = options.privateKey || process.env.PRIVATE_KEY
   const walletAddress = options.walletAddress || process.env.WALLET_ADDRESS
   const sessionKey = options.sessionKey || process.env.SESSION_KEY
+  const viewAddress = options.viewAddress || process.env.VIEW_ADDRESS
   const warmStorageAddress = options.warmStorageAddress || process.env.WARM_STORAGE_ADDRESS
 
   const rpcUrl = getRpcUrl(options)
@@ -59,7 +62,12 @@ export function parseCLIAuth(options: CLIAuthOptions): Partial<SynapseSetupConfi
   const config: any = {}
 
   if (privateKey) config.privateKey = privateKey
-  if (walletAddress) config.walletAddress = walletAddress
+  if (viewAddress) {
+    config.walletAddress = viewAddress
+    config.readOnly = true
+  } else if (walletAddress) {
+    config.walletAddress = walletAddress
+  }
   if (sessionKey) config.sessionKey = sessionKey
   if (rpcUrl) config.rpcUrl = rpcUrl
   if (warmStorageAddress) config.warmStorageAddress = warmStorageAddress

src/utils/cli-options.ts

@@ -13,6 +13,7 @@ import { type Command, Option } from 'commander'
  * - --private-key for standard authentication
  * - --wallet-address for session key authentication
  * - --session-key for session key authentication
+ * - --view-address for read-only authentication (no signing, requires wallet address)
  * - --network for network selection (mainnet or calibration)
  * - --rpc-url for network configuration (overrides --network)
  *
@@ -28,8 +29,8 @@ import { type Command, Option } from 'commander'
  *   .description('Do something')
  *   .option('--my-option <value>', 'My custom option')
  *   .action(async (options) => {
- *     // options will include: privateKey, walletAddress, sessionKey, network, rpcUrl, myOption
- *     const { privateKey, walletAddress, sessionKey, network, rpcUrl, myOption } = options
+ *     // options will include: privateKey, walletAddress, sessionKey, viewAddress, network, rpcUrl, myOption
+ *     const { privateKey, walletAddress, sessionKey, viewAddress, network, rpcUrl, myOption } = options
  *   })
  *
  * // Add authentication options after the command is fully defined
@@ -41,6 +42,11 @@ export function addAuthOptions(command: Command): Command {
     .option('--private-key <key>', 'Private key for standard auth (can also use PRIVATE_KEY env)')
     .option('--wallet-address <address>', 'Wallet address for session key auth (can also use WALLET_ADDRESS env)')
     .option('--session-key <key>', 'Session key for session key auth (can also use SESSION_KEY env)')
+    .addOption(
+      new Option('--view-address <address>', 'View-only mode (no signing) for the specified wallet address').env(
+        'VIEW_ADDRESS'
+      )
+    )
 
   return addNetworkOptions(command)
     .addOption(