ObliviousSyncProvider
SIP Protocol API Reference v0.7.4
SIP Protocol API Reference / ObliviousSyncProvider
Interface: ObliviousSyncProvider
Section titled “Interface: ObliviousSyncProvider”Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23166
Oblivious Sync Provider Interface
This is the core interface that sync services must implement. The service processes queries but learns NOTHING about:
- Which notes belong to the user
- When the user spends
- Transaction patterns or amounts
Implementation Requirements
Section titled “Implementation Requirements”- Query Processing: Must process encrypted queries without decryption
- Note Scanning: Return all potentially matching notes (over-approximate)
- No Logging: Must not log query content or patterns
- Stateless: Should not maintain per-user state
Properties
Section titled “Properties”
readonlyname:string
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23170
Get provider name/identifier
supportedChains
Section titled “supportedChains”
readonlysupportedChains:string[]
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23174
Supported chains
Methods
Section titled “Methods”initialize()
Section titled “initialize()”initialize():
Promise<void>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23178
Initialize the provider
Returns
Section titled “Returns”Promise<void>
getHealth()
Section titled “getHealth()”getHealth(
chainId):Promise<SyncServiceHealth>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23185
Check health of sync service for a chain
Parameters
Section titled “Parameters”chainId
Section titled “chainId”string
Chain to check
Returns
Section titled “Returns”Promise<SyncServiceHealth>
Health information
scanForNotes()
Section titled “scanForNotes()”scanForNotes(
viewingKeyPublic,blockRange):Promise<EncryptedNote[]>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23196
Scan for notes belonging to a viewing key (oblivious)
The service returns ALL notes that COULD belong to the viewing key, without knowing which ones actually do. The user filters locally.
Parameters
Section titled “Parameters”viewingKeyPublic
Section titled “viewingKeyPublic”`0x${string}`
Public viewing key (service sees this)
blockRange
Section titled “blockRange”Blocks to scan
Returns
Section titled “Returns”Promise<EncryptedNote[]>
Encrypted notes that might belong to user
checkNullifiers()
Section titled “checkNullifiers()”checkNullifiers(
nullifiers):Promise<Map<`0x${string}`,boolean>>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23206
Check if nullifiers have been spent (oblivious)
The service checks nullifiers but cannot correlate them to specific notes due to the sync randomness included in derivation.
Parameters
Section titled “Parameters”nullifiers
Section titled “nullifiers”Oblivious nullifiers to check
Returns
Section titled “Returns”Promise<Map<`0x${string}`, boolean>>
Map of nullifier → spent status
getMerkleProofs()
Section titled “getMerkleProofs()”getMerkleProofs(
commitments,chainId):Promise<Map<`0x${string}`,MerkleProof>>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23214
Get Merkle proofs for note inclusion
Parameters
Section titled “Parameters”commitments
Section titled “commitments”`0x${string}`[]
Note commitments to get proofs for
chainId
Section titled “chainId”string
Chain ID
Returns
Section titled “Returns”Promise<Map<`0x${string}`, MerkleProof>>
Merkle proofs for each commitment
executeObliviousQuery()
Section titled “executeObliviousQuery()”executeObliviousQuery(
query):Promise<ObliviousSyncResponse>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23224
Execute oblivious sync query
This is the fully oblivious query method where the query itself is encrypted and the service learns nothing.
Parameters
Section titled “Parameters”Encrypted oblivious query
Returns
Section titled “Returns”Promise<ObliviousSyncResponse>
Sync response with encrypted notes
getCurrentHeight()
Section titled “getCurrentHeight()”getCurrentHeight(
chainId):Promise<bigint>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23231
Get current block height for a chain
Parameters
Section titled “Parameters”chainId
Section titled “chainId”string
Chain to query
Returns
Section titled “Returns”Promise<bigint>
Current block height
subscribeToNotes()
Section titled “subscribeToNotes()”subscribeToNotes(
viewingKeyPublic,chainId,callback): () =>void
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23240
Subscribe to new notes (streaming)
Parameters
Section titled “Parameters”viewingKeyPublic
Section titled “viewingKeyPublic”`0x${string}`
Public viewing key
chainId
Section titled “chainId”string
Chain to watch
callback
Section titled “callback”(notes) => void
Called when new notes found
Returns
Section titled “Returns”Unsubscribe function
():
void
Returns
Section titled “Returns”void
shutdown()
Section titled “shutdown()”shutdown():
Promise<void>
Defined in: @sip-protocol/sdk/dist/index-DXh2IGkz.d.ts:23244
Shutdown the provider
Returns
Section titled “Returns”Promise<void>