Smart Contract Interaction

The 21X SDK enables seamless interaction with the platform's smart contracts deployed on the Polygon network. The provided OrderBook class allows users to manage their trading activity directly on the blockchain, including setting token allowances, creating and canceling orders, and retrieving balances.

---

Initializing the OrderBook Class

The OrderBook class is designed to interact with the 21X platform's smart contract on the Polygon network. It requires signing transactions, and the SDK provides a configurable middleware for transaction management.

Configuration

Currently, the OrderBook class utilizes the Web3.py library to sign and send transactions. This requires the user's private key during initialization. However, the middleware layer for transaction handling is designed to be flexible, allowing for integration with alternative mechanisms in the future (e.g., secure APIs or third-party signing services).

Constructor Parameters:

• rpc_url (str): The RPC URL of the Polygon node.

• private_key (str): The private key for signing transactions. (This is optional if an external middleware is used to handle transaction signing.)

• contract_address (str): The address of the OrderBook smart contract.

Example:

from x21_sdk import OrderBook

# Initialize the OrderBook class
order_book = OrderBook(
  private_key="your_private_key",
  orderbook_addr="0xOrderBookAddress",
  rpc_url="https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
)

Middleware for Transactions

The SDK's design abstracts transaction signing and sending through a middleware layer. This allows the implementation to be swapped or extended with minimal changes to your codebase. For instance:

• You can integrate a custom API for signing and broadcasting transactions.

• Security policies or hardware modules can be incorporated into the middleware.

In future releases, the SDK will provide a streamlined way to configure alternative transaction handlers.

---

Overview of Contract Methods

The following methods are available for interacting with the smart contract through the OrderBook class:

Key Methods:

• get_balance: Fetches the current balance of base and quote tokens.

• get_allowance: Fetches the current allowance of base and quote tokens.

• set_base_allowance: Sets the allowance for the base token.

• set_quote_allowance: Sets the allowance for the quote token.

• create_buy_order: Creates a buy order for a trading pair.

• create_sell_order: Creates a sell order for a trading pair.

• cancel_buy_order: Cancels an existing buy order.

• cancel_sell_order: Cancels an existing sell order.

Refer to the detailed method documentation below for usage examples and parameters.

---

get_balance

Fetches the current balance of the base and quote tokens for the specified trading pair.

Returns:

• Pair: An object containing:

  • base (Decimal): Balance of the base token.

  • quote (Decimal): Balance of the quote token.

Example:

balance = order_book.get_balance()
print(f"Base Token Balance: {balance.base}")
print(f"Quote Token Balance: {balance.quote}")

---

get_allowance

Fetches the current allowance of the base and quote tokens for the specified trading pair.

Returns:

• Pair: An object containing:

  • base (Decimal): Allowance of the base token.

  • quote (Decimal): Allowance of the quote token.

Example:

allowance = order_book.get_allowance()
print(f"Base Token Allowance: {allowance.base}")
print(f"Quote Token Allowance: {allowance.quote}")

---

set_base_allowance

Sets the spending allowance for the base token. This allowance is required for creating sell orders. The amount specified will be approved for use by the smart contract.

Parameters:

• amount (Decimal): The amount of the base token to approve.

Example:

order_book.set_base_allowance(amount=Decimal('1000'))

---

set_quote_allowance

Sets the spending allowance for the quote token. This allowance is required for creating buy orders. The amount specified will be approved for use by the smart contract.

Parameters:

• amount (Decimal): The amount of the quote token to approve.

Example:

order_book.set_quote_allowance(amount=Decimal('1000'))

---

create_buy_order

Creates a buy order for the specified quantity and price. Optionally, the method can automatically set the required allowance if allowance=True.

Parameters:

• quantity (Decimal): The amount of the base token to buy.

• price (Decimal): The price per unit of the base token in terms of the quote token.

• auto_allowance (bool, optional): Automatically sets the required allowance for the quote token. Defaults to True.

Example:

order_book.create_buy_order(quantity=Decimal('10'), price=Decimal('1.5'), auto_allowance=True)

---

create_sell_order

Creates a sell order for the specified quantity and price. Optionally, the method can automatically set the required allowance if allowance=True.

Parameters:

• quantity (Decimal): The amount of the base token to sell.

• price (Decimal): The price per unit of the base token in terms of the quote token.

• auto_allowance (bool, optional): Automatically sets the required allowance for the base token. Defaults to True.

Example:

order_book.create_sell_order(quantity=Decimal('5'), price=Decimal('2.0'), auto_allowance=True)

---

cancel_buy_order

Cancels an existing buy order using its unique order ID.

Parameters:

• order_id (int): The ID of the buy order to cancel.

Example:

order_book.cancel_buy_order(order_id=1234)

---

cancel_sell_order

Cancels an existing sell order using its unique order ID.

Parameters:

• order_id (int): The ID of the sell order to cancel.

Example:

order_book.cancel_sell_order(order_id=5678)

---

Notes on Usage

1. Allowances: Before creating buy or sell orders, ensure sufficient allowances are set for the respective tokens. If auto_allowance=True is passed during order creation, the SDK will handle this step automatically.

2. Balances: Always check your token balances using get_balance() to ensure you have sufficient funds to place orders.

3. Order Cancellation: Use the respective cancel_buy_order or cancel_sell_order methods to cancel pending orders. Ensure the correct order ID is provided.

4. Error Handling: All methods interact with the blockchain. Ensure your wallet is funded with sufficient MATIC to cover gas fees for these transactions.