Developer SDKs

Obscura Typescript SDK

Installation

To integrate the Obscura SDK into your project, install the required packages:

npm install @obscura/node@latest @wagmi/core viem@2.x

The SDK facilitates interactions with the relayer. Actions like creating wallets or depositing tokens require signing messages or approving tokens using your Solana wallet. We recommend using wagmi and viem for these tasks.

---

Configuration Setup

Create Config

Set up and export a new Obscura configuration using createConfig.

import { createConfig } from "@obscura/node"
import { createPublicClient, http } from 'viem'
import { solana } from 'viem/chains'

const viemClient = createPublicClient({
  chain: solana,
  transport: http()
})

export const config = createConfig({
  anonymousPoolAddress: "0xabc123def456789ghijklmno",
  priceReporterUrl: "mainnet.price-reporter.obscura.network",
  relayerUrl: "mainnet.cluster0.obscura.network",
  viemClient,
})

Environment Setup

• Environment Variables: Add a .env file in the root of your project to expose a TOKEN_MAPPING variable.

• Node Version: Use Node v22 for built-in WebSocket support. For older versions, include a WebSocket client like ws.

• Modules: This SDK exclusively uses ES Modules. Check tool-specific ESM guides for compatibility.

• Typescript Configuration: Refer to the example tsconfig.json in the documentation repo.

---

Key Concepts

Relayer

Relayers manage wallets and execute matching and settlement operations.

• Task Queues: Relayers maintain a queue of tasks for each wallet. Use getWalletFromRelayer for current state and getBackOfQueueWallet to view the wallet after all pending tasks.

Wallet

A wallet contains balances, orders, and keys.

• Wallet creation requires signing a message with your Solana wallet, generating a derivation key for secure operations.

---

SDK Components

Config

The Config object stores wallet state and derives keys for API requests. Actions like placing orders require the Config object as a parameter.

Auth Config

For API key-based access, use the AuthConfig object to interact with the relayer. Managed wallets do not require this object.

External Config

The ExternalConfig object is for externally managed wallets, allowing users to custody their own secrets and derive keys as needed.

---

Core Actions

Wallet Management

• Create a Wallet: Initialize a wallet with createWallet.

• Lookup Wallet: Retrieve an existing wallet using lookupWallet.

• Fetch Wallet State: Use getWalletFromRelayer or getBackOfQueueWallet for real-time state or queued state.

Deposits and Withdrawals

• Deposit: Transfer tokens into your Obscura wallet using executeDeposit, which handles token approvals automatically.

• Withdraw: Transfer tokens back to your Solana wallet with executeWithdrawal.

Order Management

• Place Orders: Use createOrder to place trades with parameters like base/quote pairs, order type, size, and price.

• Cancel Orders: Cancel active trades with cancelOrder.

• Order History: Retrieve historical order data using getOrderHistory.

---

External (Atomic) Matching

Obscura supports matching between:

1. Internal Parties: Trades within the anonymous pool.

2. External Parties: Trades involving external participants not within the pool.

Generating an External Match

• Request a quote using getExternalMatchQuote.

• Assemble the quote into an executable bundle with assembleExternalQuote.

• Submit the transaction to finalize the match.

---

Key Management

Externally Managed Wallets

Users can fully manage their wallet secrets, including:

• Wallet Secrets: Secure cryptographic materials for authentication and encryption.

• ExternalConfig: A configuration object linking external keys to the SDK.

Key Rotation

To enhance security, rotate keys during operations. The SDK supports key rotation for actions like deposits, withdrawals, and order placements.

---

Example Usage

Creating a Wallet

import { createWallet } from "@obscura/node"

await createWallet(config).then(() => console.log("Wallet created successfully"))

Placing an Order

import { createOrder } from "@obscura/node"

await createOrder(config, {
  base: "0xabc123",
  quote: "0xdef456",
  side: "buy",
  amount: BigInt(1000000),
  worstCasePrice: "5000",
})

Executing a Deposit

import { executeDeposit } from "@obscura/node"

await executeDeposit(config, {
  mint: "0xabc123",
  amount: BigInt(1000000),
})

---

Advanced Features

Obscura’s SDK is designed for flexibility and scalability, allowing integration with various trading and operational workflows. Explore the detailed documentation for additional features, including Collaborative SNARKs, Indications of Interest, and MPC-ZKP Architecture.