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 [email protected]
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
.envfile in the root of your project to expose aTOKEN_MAPPINGvariable.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.jsonin 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
getWalletFromRelayerfor current state andgetBackOfQueueWalletto 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
getWalletFromRelayerorgetBackOfQueueWalletfor 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
createOrderto 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:
Internal Parties: Trades within the anonymous pool.
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.
Last updated