sdk/
lib.rs

1//! Real Markets Matching Engine SDK
2//!
3//! This SDK provides a Rust client for interacting with the Real Markets matching engine
4//! via JSON-RPC over HTTP. It includes functionality for submitting transactions containing
5//! orders, canceling orders, and managing cryptographic signatures.
6//!
7//! ## Quick Start
8//!
9//! ```rust,no_run
10//! use sdk::{SigningClient, crypto::Signer, types::SubmitOrderRequest};
11//!
12//! #[tokio::main]
13//! async fn main() -> anyhow::Result<()> {
14//!     // a private key in IOTA bech32 form (`iotaprivkey1…`), not hex
15//!     let signer: Signer =
16//!         "iotaprivkey1qrsd2u9ztqr6z2y78sp2ch8kcyak9cx3ezphkpp4acqaqruajxr6qye2645".into();
17//!
18//!     // Create a testnet client (automatically handles signing and nonces)
19//!     let client = SigningClient::new_testnet(signer)?;
20//!
21//!     // `market` and `account` are on-chain object ids — `0x`-prefixed hex,
22//!     // never ticker symbols; anything else fails in `build()`
23//!     let order = SubmitOrderRequest::builder()
24//!         .market("0x5efc5ad00c209baf4c5d77dfd1be18e8b50916e53adbe2142ae1b47af445303c")
25//!         .account("0xcc6ebf909253ea35314bb28d91321f6415827c01790fba84aaf570c87372850a")
26//!         .buy()
27//!         .limit_order("50000.00")
28//!         .quantity("0.1")
29//!         .good_till_cancel()
30//!         .build()?;
31//!
32//!     // a rejected order also comes back as `Ok`: inspect `report.success`
33//!     let report = client
34//!         .submit_order(order, Some("unique-request-id".to_string()))
35//!         .await?;
36//!     println!("Order submitted: {:?}", report);
37//!
38//!     Ok(())
39//! }
40//! ```
41//!
42//! ## Architecture
43//!
44//! The SDK uses a transaction-based approach where:
45//! 1. **Commands** (like `SubmitOrder` or `CancelOrder`) are grouped into a `TransactionPayload`
46//! 2. The payload is serialized, signed cryptographically, and wrapped in a `Transaction`
47//! 3. Transactions are sent to the matching engine via JSON-RPC HTTP calls
48//!
49//! ## Available Operations
50//!
51//! - **Submit Orders**: Create market or limit orders with various time-in-force options
52//! - **Cancel Orders**: Cancel one order by id or client id, or every order an
53//!   account holds in one market
54//! - **Liquidate Positions**: Trigger liquidation of a distressed account
55//! - **Margin Parameters**: Switch a position to cross or isolated margin, or set
56//!   its IMR — each must be alone in its transaction
57//! - **Batches**: Send several commands in one signed transaction
58//! - **Health Checks**: Read the engine's sequencer and settlement-chain heights
59//! - **Version Info**: Get matching engine version
60//! - **Chain Id**: Read the chain id the endpoint expects in signed payloads
61//!
62//! ## Modules
63//!
64//! - [`client`]: HTTP JSON-RPC client for connecting to the matching engine
65//! - [`signing_client`]: High-level client with automatic transaction signing
66//! - [`types`]: Data types for orders, transactions, and API responses
67//! - [`crypto`]: Cryptographic utilities for signing and verification
68
69pub use client::Client;
70pub use networks::Network;
71pub use signing_client::{SigningClient, SigningClientBuilder};
72
73pub mod client;
74pub mod signing_client;
75
76/// Data types and structures for interacting with the matching engine API.
77///
78/// This module provides all the necessary types for constructing transactions,
79/// submitting orders, canceling orders, and handling responses from the matching engine.
80/// It includes builder patterns for type-safe construction and comprehensive validation.
81pub mod types {
82    pub use types::{
83        api::{
84            cancel_order::*,
85            errors::*,
86            liquidate_position::*,
87            rate_limit::*,
88            receipts::{OrderPlaced, OrdersTerminated, TradeExecuted},
89            set_imr::*,
90            submit_order::*,
91            switch_to_cross::*,
92            switch_to_isolated::*,
93            transaction::*,
94            transaction_report::*,
95        },
96        common::{OrderError, OrderStatus, OrderType, Side, TimeInForce},
97    };
98}
99
100/// Cryptographic utilities for signing transactions and managing keys.
101///
102/// This module provides functionality for creating digital signatures required
103/// by the matching engine, managing keystores, and verifying message signatures.
104/// All transactions must be cryptographically signed before submission.
105pub mod crypto {
106    pub use crypto::{Signer, keystore::Keystore, raw::RawSigner, verify_message_signature};
107}
sdk/lib.rs

sdk/
lib.rs
