refactor nonce-manager and use API Key dict only in signer

- pass API key directly to signer
- pass a list of arbitrary API keys to nonce manager
- setup stores multiple API keys

Author: alexvelea

examples/README.md

@@ -9,14 +9,14 @@
   - the API key config is saved in a local file `./api_key_config.json`
 
 ## Start trading on testnet
-- `create_modify_cancel_order.py`
+- `create_modify_cancel_order_http.py`
   - creates an ask (sell) order for 0.1 ETH @ $4050
   - modified the order and increases the size to 0.11 ETH and increases the price to $4100
   - cancels the order
   - Note: all of these operations use the client order index of the order. You can use the order from the exchange as well
 
-- `ws_send_tx.py`
-  - same flow as `create_modify_cancel_order.py`
+- `create_modify_cancel_order_ws.py`
+  - same flow as `create_modify_cancel_order_http.py`
   - sends TXs over WS instead of HTTP
 
 - `create_grouped_ioc_with_attached_sl_tp.py`
@@ -43,6 +43,24 @@ What about the order types? Just as normal orders, SL/TP orders trigger an order
 - market order
 - limit IOC / GTC
 
+### Modify leverage / Margin Mode (Cross, Isolated) / Add Collateral to isolated-only positions
+- `margin_eth_20x_cross_http`
+  - sets ETH market to 20x leverage and cross-margin mode, using HTTP
+- `margin_eth_50x_isolate_ws`
+  - sets ETH market to 50x leverage and isolated margin mode, using HTTP
+- `margin_eth_add_collateral_http.py`
+  - adds $10.5 USDC to the ETH position (must be opened and in isolated mode)
+- `margin_eth_remove_collateral_ws.py`
+  - removes $5 USDC from the ETH position (must be opened and in isolated mode)
+
+### Batch orders
+- `send_batch_tx_http.py`
+  - sends multiple orders in a single HTTP request
+- `send_batch_tx_ws.py`
+  - sends multiple orders in a single WS request`
+
+Batch TXs will be executed back to back, without the possibility of other TXs interfering.
+
 ## Setup steps for mainnet
 - deposit money on Lighter to create an account first
 - change the URL to `mainnet.zklighter.elliot.ai`

examples/create_grouped_ioc_with_attached_sl_tp.py

@@ -7,11 +7,19 @@
 async def main():
     client, api_client, _ = default_example_setup()
 
+    # Sell some ETH at $2500
+    # The size of the SL/TP orders will be equal to the size of the executed order
+
+    # set SL trigger price at 5000 and limit price at 5050
+    # set TP trigger price at 1500 and limit price at 1550
+    # Note: set the limit price to be higher than the SL/TP trigger price to ensure the order will be filled
+    # If the mark price of ETH reaches 1500, there might be no one willing to sell you ETH at 1500, so trying to buy at 1550 would increase the fill rate
+
     ioc_order = CreateOrderTxReq(
         MarketIndex=0,
         ClientOrderIndex=0,
         BaseAmount=1000,  # 0.1 ETH
-        Price=300000,  # $3000
+        Price=2500_00,  # $2500
         IsAsk=1,  # sell
         Type=lighter.SignerClient.ORDER_TYPE_LIMIT,
         TimeInForce=lighter.SignerClient.ORDER_TIME_IN_FORCE_IMMEDIATE_OR_CANCEL,
@@ -25,25 +33,25 @@ async def main():
         MarketIndex=0,
         ClientOrderIndex=0,
         BaseAmount=0,
-        Price=300000,
+        Price=1550_00,
         IsAsk=0,
         Type=lighter.SignerClient.ORDER_TYPE_TAKE_PROFIT_LIMIT,
         TimeInForce=lighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
         ReduceOnly=1,
-        TriggerPrice=300000,
+        TriggerPrice=1500_00,
         OrderExpiry=-1,
     )
 
     stop_loss_order = CreateOrderTxReq(
         MarketIndex=0,
         ClientOrderIndex=0,
         BaseAmount=0,
-        Price=500000,
+        Price=5050_00,
         IsAsk=0,
         Type=lighter.SignerClient.ORDER_TYPE_STOP_LOSS_LIMIT,
         TimeInForce=lighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
         ReduceOnly=1,
-        TriggerPrice=500000,
+        TriggerPrice=5000_00,
         OrderExpiry=-1,
     )
 

examples/create_modify_cancel_order.py …mples/create_modify_cancel_order_http.pyexamples/create_modify_cancel_order.py renamed to examples/create_modify_cancel_order_http.py examples/create_modify_cancel_order.py renamed to examples/create_modify_cancel_order_http.py

@@ -5,8 +5,10 @@
 
 async def main():
     client, api_client, _ = default_example_setup()
+    client.check_client()
 
     # create order
+    api_key_index, nonce = client.nonce_manager.next_nonce()
     tx, tx_hash, err = await client.create_order(
         market_index=0,
         client_order_index=123,
@@ -17,27 +19,37 @@ async def main():
         time_in_force=lighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
         reduce_only=False,
         trigger_price=0,
+        nonce=nonce,
+        api_key_index=api_key_index,
     )
     print(f"Create Order {tx=} {tx_hash=} {err=}")
     if err is not None:
         raise Exception(err)
 
-    # create order
+    ## modify order
+    # use the same API key so the TX goes after the create order TX
+    api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     tx, tx_hash, err = await client.modify_order(
         market_index=0,
         order_index=123,
         base_amount=1100,  # 0.11 ETH
         price=410000,  # $4100
         trigger_price=0,
+        nonce=nonce,
+        api_key_index=api_key_index,
     )
     print(f"Modify Order {tx=} {tx_hash=} {err=}")
     if err is not None:
         raise Exception(err)
 
-    # cancel order
+    ## cancel order
+    # use the same API key so the TX goes after the modify order TX
+    api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
     tx, tx_hash, err = await client.cancel_order(
         market_index=0,
         order_index=123,
+        nonce=nonce,
+        api_key_index=api_key_index,
     )
     print(f"Cancel Order {tx=} {tx_hash=} {err=}")
     if err is not None:

examples/ws_send_tx.py examples/create_modify_cancel_order_ws.pyexamples/ws_send_tx.py renamed to examples/create_modify_cancel_order_ws.py

@@ -1,38 +1,21 @@
-import json
 import websockets
 import asyncio
 
 import lighter
-from utils import default_example_setup
-
-
-async def ws_send_tx(ws_client: websockets.ClientConnection, tx_type, tx_info):
-    await ws_client.send(
-        json.dumps(
-            {
-                "type": "jsonapi/sendtx",
-                "data": {
-                    "id": f"my_random_id_{12345678}",  # optional, helps id the response
-                    "tx_type": tx_type,
-                    "tx_info": json.loads(tx_info),
-                },
-            }
-        )
-    )
-
-    print("Response:", await ws_client.recv())
+from utils import default_example_setup, ws_send_tx
 
 
 # this example does the same thing as the create_modify_cancel_order.py example, but sends the TX over WS instead of HTTP
 async def main():
     client, api_client, ws_client_promise = default_example_setup()
 
-    # setup WS client and print connected message
+    # set up WS client and print a connected message
     ws_client: websockets.ClientConnection = await ws_client_promise
     print("Received:", await ws_client.recv())
 
     # create order
-    tx_type, tx_info, err = client.sign_create_order(
+    api_key_index, nonce = client.nonce_manager.next_nonce()
+    tx_type, tx_info, tx_hash, err = client.sign_create_order(
         market_index=0,
         client_order_index=123,
         base_amount=1000,  # 0.1 ETH
@@ -42,31 +25,41 @@ async def main():
         time_in_force=lighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
         reduce_only=False,
         trigger_price=0,
+        nonce=nonce,
+        api_key_index=api_key_index,
     )
     if err is not None:
         raise Exception(err)
-    await ws_send_tx(ws_client, tx_type, tx_info)
+    await ws_send_tx(ws_client, tx_type, tx_info, tx_hash)
 
-    # modify order
-    tx_type, tx_info, err = client.sign_modify_order(
+    ## modify order
+    # use the same API key so the TX goes after the create order TX
+    api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
+    tx_type, tx_info, tx_hash, err = client.sign_modify_order(
         market_index=0,
         order_index=123,
         base_amount=1100,  # 0.11 ETH
         price=410000,  # $4100
         trigger_price=0,
+        nonce=nonce,
+        api_key_index=api_key_index,
     )
     if err is not None:
         raise Exception(err)
-    await ws_send_tx(ws_client, tx_type, tx_info)
+    await ws_send_tx(ws_client, tx_type, tx_info, tx_hash)
 
-    # cancel order
-    tx_type, tx_info, err = client.sign_cancel_order(
+    ## cancel order
+    # use the same API key so the TX goes after the modify order TX
+    api_key_index, nonce = client.nonce_manager.next_nonce(api_key_index)
+    tx_type, tx_info, tx_hash, err = client.sign_cancel_order(
         market_index=0,
         order_index=123,
+        nonce=nonce,
+        api_key_index=api_key_index,
     )
     if err is not None:
         raise Exception(err)
-    await ws_send_tx(ws_client, tx_type, tx_info)
+    await ws_send_tx(ws_client, tx_type, tx_info, tx_hash)
 
     await client.close()
     await api_client.close()

examples/create_position_tied_sl_tl.py

@@ -8,30 +8,40 @@
 async def main():
     client, api_client, _ = default_example_setup()
 
+    # Creates a position tied SL/TP pair
+    # The SL/TP orders will close your whole position, even if you add/remove from it later on
+    # if the positions reach 0 or switches from short -> long, the orders are canceled
+
+    # this particular example, sets the SL/TP for a short position
+    # set SL trigger price at 5000 and limit price at 5050
+    # set TP trigger price at 1500 and limit price at 1550
+    # Note: set the limit price to be higher than the SL/TP trigger price to ensure the order will be filled
+    # If the mark price of ETH reaches 1500, there might be no one willing to sell you ETH at 1500, so trying to buy at 1550 would increase the fill rate
+
     # Create a One-Cancels-the-Other grouped order with a take-profit and a stop-loss order
     take_profit_order = CreateOrderTxReq(
         MarketIndex=0,
         ClientOrderIndex=0,
         BaseAmount=0,
-        Price=300000,
+        Price=1550_00,
         IsAsk=0,
         Type=lighter.SignerClient.ORDER_TYPE_TAKE_PROFIT_LIMIT,
         TimeInForce=lighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
         ReduceOnly=1,
-        TriggerPrice=300000,
+        TriggerPrice=1500_00,
         OrderExpiry=-1,
     )
 
     stop_loss_order = CreateOrderTxReq(
         MarketIndex=0,
         ClientOrderIndex=0,
         BaseAmount=0,
-        Price=500000,
+        Price=4050_00,
         IsAsk=0,
         Type=lighter.SignerClient.ORDER_TYPE_STOP_LOSS_LIMIT,
         TimeInForce=lighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
         ReduceOnly=1,
-        TriggerPrice=500000,
+        TriggerPrice=4000_00,
         OrderExpiry=-1,
     )
 

examples/create_with_multiple_keys.py

@@ -1,31 +1,13 @@
-import asyncio
-import lighter
-
+import time
 
-BASE_URL = "https://testnet.zklighter.elliot.ai"
-# use examples/system_setup.py or the apikeys page (for mainnet) to generate new api keys
-KEYS = {
-    5: "API_PRIVATE_KEY_5",
-    6: "API_PRIVATE_KEY_6",
-    7: "API_PRIVATE_KEY_7",
-}
-ACCOUNT_INDEX = 100  # replace with your account_index
+import asyncio
+from utils import default_example_setup
 
 
 async def main():
-    client = lighter.SignerClient(
-        url=BASE_URL,
-        private_key=KEYS[5],
-        account_index=ACCOUNT_INDEX,
-        api_key_index=5,
-        max_api_key_index=7,
-        private_keys=KEYS,
-    )
-
-    err = client.check_client()
-    if err is not None:
-        print(f"CheckClient error: {err}")
-        return
+    client, api_client, _ = default_example_setup()
+
+    # create 20 orders. The client will use as many API keys as it was configured.
 
     for i in range(20):
         res_tuple = await client.create_order(
@@ -34,14 +16,16 @@ async def main():
             base_amount=100000 + i,
             price=385000 + i,
             is_ask=True,
-            order_type=lighter.SignerClient.ORDER_TYPE_LIMIT,
-            time_in_force=lighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
+            order_type=client.ORDER_TYPE_LIMIT,
+            time_in_force=client.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
             reduce_only=False,
             trigger_price=0,
         )
         print(res_tuple)
 
-    await client.cancel_all_orders(time_in_force=client.CANCEL_ALL_TIF_IMMEDIATE, time=0)
+    # wait for orders to be created
+    time.sleep(1)
+    await client.cancel_all_orders(time_in_force=client.CANCEL_ALL_TIF_IMMEDIATE, timestamp_ms=0)
 
 
 if __name__ == "__main__":

examples/margin_eth_20x_cross_http.py

@@ -0,0 +1,29 @@
+import asyncio
+from utils import default_example_setup
+
+
+async def main():
+    client, api_client, _ = default_example_setup()
+
+    # Note: the HTTP method `update_leverage` receives `leverage` as the argument,
+    # while the WS one that calls `sign_update_leverage` to get the TX to send it directly over WS
+    # receives `fraction` as the argument, which is 10_000 / leverage
+    # this was kept this way to not break backwards compatibility. Ideally, they would be consistent.
+
+    tx, tx_hash, err = await client.update_leverage(
+        market_index=0,
+        leverage=20,
+        margin_mode=client.CROSS_MARGIN_MODE
+    )
+
+    print(f"Update Leverage {tx=} {tx_hash=} {err=}")
+    if err is not None:
+        raise Exception(err)
+
+    await client.close()
+    await api_client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+