@silvana-one/orderbook

@silvana-one/orderbook

TypeScript client library for the Silvana orderbook. Works in Node.js and Browser environments. Wraps 5 gRPC services via Connect RPC.

Installation

npm install @silvana-one/orderbook

For Node.js:

npm install @connectrpc/connect-node

For Browser:

npm install @connectrpc/connect-web

Usage

Node.js

import { createGrpcTransport } from "@connectrpc/connect-node";
import {
  OrderbookClient,
  OrderType,
  TimeInForce,
} from "@silvana-one/orderbook";

const transport = createGrpcTransport({
  baseUrl: "https://your-orderbook-server:port",
});

const client = new OrderbookClient({
  transport,
  token: "your-jwt-token",
});

// Get markets
const markets = await client.getMarkets();
console.log(markets.markets);

// Submit an order
const order = await client.submitOrder({
  marketId: "BTC-USD",
  orderType: OrderType.BID,
  price: "50000.00",
  quantity: "0.1",
  timeInForce: TimeInForce.GTC,
});

Browser

import { createGrpcWebTransport } from "@connectrpc/connect-web";
import {
  OrderbookClient,
  OrderType,
  TimeInForce,
} from "@silvana-one/orderbook";

const transport = createGrpcWebTransport({
  baseUrl: "https://your-orderbook-server:port",
});

const client = new OrderbookClient({
  transport,
  token: "your-jwt-token",
});

// Same API as Node.js
const markets = await client.getMarkets();

Clients

OrderbookClient

Trading operations, order management, market data, and RFQ. Requires JWT authentication.

import { OrderbookClient } from "@silvana-one/orderbook";

const client = new OrderbookClient({ transport, token });

// Trading
await client.submitOrder({ ... });
await client.cancelOrder({ orderId: 123n });
await client.getOrders({ marketId: "BTC-USD" });

// Market data
await client.getOrderbookDepth({ marketId: "BTC-USD", depth: 10 });
await client.getMarketData({ marketIds: ["BTC-USD"] });

// RFQ
const quotes = await client.requestQuotes({ marketId: "BTC-USD", direction: "buy", quantity: "0.5" });
await client.acceptQuote({ rfqId: quotes.rfqId, quoteId: quotes.quotes[0].quoteId });

// Streaming
for await (const update of client.subscribeOrderbook({ marketId: "BTC-USD" })) {
  console.log(update);
}

SettlementClient

DVP settlement orchestration and RFQ handling. Requires JWT authentication.

import { SettlementClient } from "@silvana-one/orderbook";

const client = new SettlementClient({ transport, token });

await client.getPendingProposals({ partyId: "party-1" });
await client.getSettlementStatus({ settlementId: "settlement-1" });

// Bidirectional streaming for settlement flow and RFQ
const stream = client.settlementStream(messages);

LedgerClient

Two-phase transaction signing, balance/contract queries, and cloud agent onboarding. JWT authentication for most RPCs; onboarding RPCs use message-level Ed25519 signing.

import { LedgerClient } from "@silvana-one/orderbook";

const client = new LedgerClient({ transport, token });

// Queries
await client.getBalances();
await client.getDsoRates();
await client.getServiceInfo();

// Two-phase transaction
const prepared = await client.prepareTransaction({ operation, params });
// ... sign hash locally ...
await client.executeTransaction({
  transactionId: prepared.transactionId,
  signature,
});

// Onboarding (no JWT needed)
const unauthClient = new LedgerClient({ transport });
await unauthClient.getAgentConfig();
await unauthClient.registerAgent({ publicKey, requestSignature });

// Streaming
for await (const contract of client.getActiveContracts({
  templateFilters: ["..."],
})) {
  console.log(contract);
}

PricingClient

External price feeds (Binance, ByBit, CoinGecko). No authentication needed.

import { PricingClient } from "@silvana-one/orderbook";

const client = new PricingClient({ transport });

await client.getPrice({ marketId: "BTC-USD" });
await client.getKlines({ marketId: "BTC-USD", interval: "1h", limit: 100 });

// Streaming
for await (const update of client.streamPrices({ marketIds: ["BTC-USD"] })) {
  console.log(update);
}

gRPC Services

The library wraps 5 gRPC services:

Service	Client	Auth	Streaming
OrderbookService	OrderbookClient	JWT	Server-streaming (subscribeOrderbook, subscribeOrders, subscribeSettlements)
SettlementService	SettlementClient	JWT	Bidirectional (settlementStream)
DAppProviderService	LedgerClient	JWT / Message signing	Server-streaming (getActiveContracts, getUpdates)
PricingService	PricingClient	None	Server-streaming (streamPrices)

Two-Phase Transaction Flow

All ledger-mutating operations use a two-phase signing protocol via LedgerClient:

• Call prepareTransaction with an operation type and parameters
• Server returns the full prepared_transaction bytes and a hash
• Verify the transaction matches the requested operation (correct template, parties, amounts)
• Sign the hash locally with Ed25519 private key
• Call executeTransaction with the signature
• Server submits the signed transaction to the Canton ledger

Operation types:

Operation	Description
TRANSFER_CC	Send Canton Coin
TRANSFER_CIP56	Send CIP-56 token
ACCEPT_CIP56	Accept incoming CIP-56 transfer
PAY_DVP_FEE	Pay DVP processing fee
PROPOSE_DVP	Create DVP proposal
ACCEPT_DVP	Accept DVP proposal
PAY_ALLOC_FEE	Pay allocation processing fee
ALLOCATE	Allocate tokens to DVP
REQUEST_PREAPPROVAL	Request TransferPreapproval
REQUEST_RECURRING_PREPAID	Request prepaid subscription
REQUEST_RECURRING_PAYASYOUGO	Request pay-as-you-go subscription
REQUEST_USER_SERVICE	Request UserService (onboarding)

Settlement Stream (Bidirectional)

SettlementClient.settlementStream() opens a long-lived bidirectional gRPC stream for RFQ handling and settlement lifecycle coordination.

Client sends: handshake, heartbeats, preconfirmation decisions, DVP lifecycle events, RFQ quotes/rejections

Server sends: handshake acknowledgement, heartbeats, settlement proposals, preconfirmation requests, RFQ requests

Key Query RPCs

Method	Client	Returns
getBalances()	Ledger	Token balances (total, locked, unlocked)
getActiveContracts()	Ledger	Stream of active contracts by template filter
getUpdates()	Ledger	Stream of ledger transactions from a given offset
getPrice()	Pricing	Bid, ask, last price for a market
getKlines()	Pricing	OHLCV candlestick data (1m to 1w intervals)
getOrders()	Orderbook	Orders with status and type filters
getOrderbookDepth()	Orderbook	Aggregated bid/offer price levels
getSettlementProposals()	Orderbook	Settlement proposals with status filter
getSettlementStatus()	Settlement	Step-by-step DVP status with buyer/seller next actions
getMarkets()	Orderbook	Available markets and their configuration
getMarketData()	Orderbook	Best bid/ask, last price, 24h volume
requestQuotes()	Orderbook	RFQ quotes from connected liquidity providers
acceptQuote()	Orderbook	Accept an LP quote, creating a settlement proposal

Server-Streaming Subscriptions

Method	Client	Payload
getActiveContracts()	Ledger	Active contracts matching template filter
getUpdates()	Ledger	Ledger transaction stream from a given offset
subscribeOrderbook()	Orderbook	Orderbook snapshots and deltas
subscribeOrders()	Orderbook	Order lifecycle events (created, filled, cancelled)
subscribeSettlements()	Orderbook	Settlement status change events
streamPrices()	Pricing	Real-time price ticks with optional orderbook and trade data

Authentication

• JWT — Self-describing Ed25519 JWT (RFC 8037) with automatic refresh. Used for Orderbook, Pricing, and Settlement RPCs. The token embeds the Ed25519 public key; the server verifies it matches the registered party.
• Message signing — Per-request Ed25519 signature on the canonical request payload, used for Ledger two-phase transactions. Server responses are also signed and should be verified using the ledger service public key.

Types

All protobuf types are exported from the package:

import {
  Order,
  OrderType,
  OrderStatus,
  TimeInForce,
  MarketType,
  SettlementStatus,
  Market,
  Instrument,
  TransactionOperation,
  TransactionStatus,
  RfqAuditEventType,
  RfqDirection,
  RfqRejectionReason,
} from "@silvana-one/orderbook";

License

Apache-2.0