fix: refreshed collab notebook

README.md

@@ -34,26 +34,19 @@ The `nibiru` package allows you to index, query, and send transactions on Nibiru
 
 The package is intended to be used by coders, developers, technically-skilled traders and  data-scientists for building trading algorithms.
 
-#### README Contents
+## Try running nibiru sdk online
 
-- [Python SDK Tutorial](#python-sdk-tutorial)
-- [Installation from `PyPI`](#installation-from-pypi)
-- [Usage](#usage)
-  - [Ex: Creating a wallet and SDK client](#ex-creating-a-wallet-and-sdk-client)
-  - [Ex: Using the faucet](#ex-using-the-faucet)
-  - [Ex: Querying chain state](#ex-querying-chain-state)
-  - [Ex: Submitting transactions](#ex-submitting-transactions)
-- [Documentation Website](#documentation-website)
-- [Contributing](#contributing)
+Open the google collab link below to try running Niburu code online: 
 
-## Python SDK Tutorial
-
-<a href="https://colab.research.google.com/github/NibiruChain/py-sdk/blob/master/examples/collab_notebook.ipynb" target="_blank">
+<a href="https://colab.research.google.com/github/NibiruChain/py-sdk/blob/main/examples/colab_notebook.ipynb" target="_blank">
 <p align="center">
   <img src="https://colab.research.google.com/assets/colab-badge.svg" style="width: 300px;">
 </p>
 </a>
 
+Or go to the [examples folder](examples) to see the codes and run Jupyter notebooks locally.
+
+## Installation
 ```bash
 pip install nibiru  # requires Python 3.8+
 ```
@@ -126,13 +119,12 @@ print(client.query.get_bank_balances(client.address))
 
 ```python
 output = client.tx.execute_msgs(
-    Msg.perp.open_position(
-        pair=pair,
-        is_long=True,
-        quote_asset_amount=10,
-        leverage=1,
-        base_asset_amount_limit=0,
-    )
+  Msg.perp.open_position(
+    pair=pair,
+    is_long=True,
+    margin=10,
+    leverage=2,
+  )
 )
 print(output)
 ```

examples/2- My first transaction.ipynb

@@ -125,9 +125,8 @@
     "    Msg.perp.open_position(\n",
     "        pair=pair,\n",
     "        is_long=True,\n",
-    "        quote_asset_amount=10,\n",
+    "        margin=10,\n",
     "        leverage=1,\n",
-    "        base_asset_amount_limit=0,\n",
     "    )\n",
     ")\n",
     "print(output)"

examples/colab_notebook.ipynb

@@ -4,83 +4,103 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Introduction to py-sdk\n",
-    "\n",
-    "The python sdk allows you to create queries and transaction to a Nibiru chain.\n",
-    "\n",
-    "It allows to interact with all of the modules and can be leveraged to automate trading strategies or monitor them.\n",
+    "# Introduction to Nibiru SDK\n",
     "\n",
+    "The python sdk allows you to create queries and send transactions to a Nibiru chain.\n",
+    "It allows to interact with all the modules and can be leveraged to automate trading strategies or monitor them.\n",
     "This notebook will guide you on opening and closing positions."
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import json\n",
-    "\n",
-    "from nibiru import Network, ChainClient, Msg, Coin"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's set up the chain to which we will be connecting to. If you have a preferred endpoint you can update these values to connect to it. Make sure that the node have the port opens for 1317, 26657 and 9090."
+    "### 1. Prepare wallet mnemonic key (or private key)\n",
+    "If you don't have a mnemonic key, generate it using some online service or run the code below:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
    "outputs": [],
    "source": [
-    "pair = \"ubtc:unusd\""
-   ]
+    "from nibiru import PrivateKey\n",
+    "mnemonic, private_key = PrivateKey.generate()\n",
+    "print(mnemonic)"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
    "source": [
-    "Next, let's make sure that the transaction we send are synchronous. This way if no error is raised when running the execute_msgs method, we are sure that the transaction was successful."
-   ]
+    "### 2. Get test tokens from the nibiru faucet\n",
+    "Faucet URL: [https://app.nibiru.fi/faucet](https://app.nibiru.fi/faucet)"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### 3. Create nibiru chain client and authenticate using mnemonic\n",
+    "The client below uses ITN-2 Nibiru testnet chain.\n",
+    "Use your mnemonic key or private key to authenticate.\n",
+    "If you took money from the faucet, your balances should not be empty."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "mnemonic = \"exclude rural knife asset egg seminar carry control thought stock topic lens embark about huge obvious reason language ripple clean cousin library punch renew\"\n",
+    "import json\n",
+    "from nibiru import Network, ChainClient, Msg, Coin\n",
+    "\n",
+    "mnemonic = \"put your mnemonic here\"\n",
     "client = ChainClient(network=Network.testnet(2))\n",
-    "client.authenticate(mnemonic=mnemonic)\n",
+    "client.authenticate(mnemonic=mnemonic)  # alternatively use private_key_hex = your_key_hex\n",
     "\n",
     "# Check balance\n",
-    "print(client.query.get_bank_balances(client.address))"
+    "print(json.dumps(client.query.get_bank_balances(client.address)[\"balances\"], indent=2))"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
    "source": [
-    "Now with those fresh token, we can open a long position"
-   ]
+    "### 4. Create a tx to open perp trading position\n",
+    "Position is: LONG (=BUY),\n",
+    "\n",
+    "pair = ubtc:unusd: prefix `u` means `μ` or micro. So `unusd = micro unusd = 1/1000_000 nusd`, same for ubtc.\n",
+    "\n",
+    "margin = 10: (value in quote amount which is unusd in our case)\n",
+    "\n",
+    "leverage = 2: your position notional will be 2 * 10"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
+    "pair = \"ubtc:unusd\"\n",
+    "\n",
     "output = client.tx.execute_msgs(\n",
     "    Msg.perp.open_position(\n",
     "        pair=pair,\n",
     "        is_long=True,\n",
-    "        quote_asset_amount=10,\n",
-    "        leverage=1,\n",
-    "        base_asset_amount_limit=0,\n",
+    "        margin=10,\n",
+    "        leverage=2,\n",
     "    )\n",
     ")\n",
     "print(output)"
@@ -90,7 +110,9 @@
    "cell_type": "markdown",
    "source": [
     "If your TX has succeeded, you should get output something like:\n",
+    "```\n",
     "ExecuteTxResp(code=0, tx_hash='946A4252423A0AC183C1BAA2B76CCB25512DC9A18861D8782EFE7F14512CBDF6', log='[]')\n",
+    "```\n",
     "Query your TX hash to get TX details:"
    ],
    "metadata": {
@@ -102,7 +124,7 @@
    "execution_count": null,
    "outputs": [],
    "source": [
-    "output = client.query.tx_by_hash(\"946A4252423A0AC183C1BAA2B76CCB25512DC9A18861D8782EFE7F14512CBDF6\")\n",
+    "output = client.query.tx_by_hash(\"707F725DA2A04FD865FA6FEAF431DF89459F6A5C076B5AF93C627979C9B6CDF1\")\n",
     "print(output)"
    ],
    "metadata": {
@@ -197,16 +219,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Multi-transactions"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "We can build multiple messages into a single transactions to be sure that they are executed consecutively.\n",
+    "## Multi-transactions\n",
+    "We can build multiple messages into a single transaction to be sure that they are executed consecutively.\n",
     "\n",
-    "It can be useful for example to send tokens after removing margins from a position"
+    "It can be useful for example to send tokens after removing margins from a position."
    ]
   },
   {
@@ -230,9 +246,8 @@
     "        Msg.perp.open_position(\n",
     "            pair=pair,\n",
     "            is_long=True,\n",
-    "            quote_asset_amount=10,\n",
+    "            margin=10,\n",
     "            leverage=1,\n",
-    "            base_asset_amount_limit=0,\n",
     "        ),\n",
     "        Msg.perp.add_margin(\n",
     "            pair=pair,\n",
@@ -245,6 +260,27 @@
     ")\n",
     "print(output)"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "position = client.query.perp.all_positions(client.address)\n",
+    "print(json.dumps(position, indent=4))"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "That's it! Good luck and happy Nibiru coding!"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
   }
  ],
  "metadata": {

nibiru/msg/perp.py

@@ -32,26 +32,26 @@ class MsgsPerp:
     def open_position(
         pair: str,
         is_long: bool,
-        quote_asset_amount: float,
+        margin: float,
         leverage: float,
-        base_asset_amount_limit: float,
+        base_asset_amount_limit: float = 0,
     ) -> 'MsgMarketOrder':
         """
         Open a posiiton using the specified parameters.
 
         Attributes:
             pair (str): The token pair
             is_long (bool): Determines whether to open with long or short exposure.
-            quote_asset_amount (float): The quote amount you want to use to buy base
+            margin (float): The margin of the position
             leverage (float): The leverage you want to use, typically between 1 and 15, depending on the maintenance
                 margin ratio of the pool.
-            base_asset_amount_limit (float): The minimum amount of base you are willing to receive for this amount of
-                quote.
+            base_asset_amount_limit (float): The minimum amount of base you are willing
+                to receive for this amount of quote.
         """
         return MsgMarketOrder(
             pair=pair,
             dir=Direction.LONG if is_long else Direction.SHORT,
-            quote_asset_amount=quote_asset_amount,
+            margin=margin,
             leverage=leverage,
             base_asset_amount_limit=base_asset_amount_limit,
         )
@@ -177,7 +177,7 @@ class MsgMarketOrder(PythonMsg):
     Attributes:
         pair (str): The token pair
         side (Side): The side, either Side.BUY or Side.SELL
-        quote_asset_amount (float): The quote amount you want to use to buy base
+        margin (float): The quote amount you want to use to buy base
         leverage (float): The leverage you want to use, typically between 1 and 15, depending on the maintenance
             margin ratio of the pool.
         base_asset_amount_limit (float): The minimum amount of base you are willing to receive for this amount of
@@ -186,7 +186,7 @@ class MsgMarketOrder(PythonMsg):
 
     pair: str
     dir: Direction
-    quote_asset_amount: float
+    margin: float
     leverage: float
     base_asset_amount_limit: float
 
@@ -203,7 +203,7 @@ def to_pb(self, sender: str) -> pb.MsgMarketOrder:
             if self.dir == Direction.LONG
             else state_pb.Direction.SHORT
         )
-        quote_asset_amount_pb = to_sdk_int(self.quote_asset_amount)
+        quote_asset_amount_pb = to_sdk_int(self.margin)
         base_asset_amount_limit_pb = to_sdk_int(self.base_asset_amount_limit)
         leverage_pb = to_sdk_dec(self.leverage)
 

tests/perp_test.py

@@ -27,9 +27,8 @@ def test_open_position(client_validator):
             Msg.perp.open_position(
                 pair=PAIR,
                 is_long=False,
-                quote_asset_amount=10,
+                margin=10,
                 leverage=10,
-                base_asset_amount_limit=0,
             )
         )
         tests.broadcast_tx_must_succeed(res=tx_output)

tests/websocket_test.py

@@ -40,9 +40,8 @@ def test_websocket_listen(client_validator, network: Network):
                 sender=client_validator.address,
                 pair=pair,
                 is_long=True,
-                quote_asset_amount=10,
+                margin=10,
                 leverage=10,
-                base_asset_amount_limit=0,
             ),
             Msg.bank.send(
                 from_address=client_validator.address,