refactor: examples by module (#262)

NibiruChain · Oct 3, 2023 · b693d2d · b693d2d
1 parent a7621f7
commit b693d2d
Show file tree

Hide file tree

Showing 12 changed files with 1,052 additions and 671 deletions.
diff --git a/.github/workflows/notebooks.yml b/.github/workflows/notebooks.yml
@@ -33,6 +33,7 @@ jobs:
       # https://www.notion.so/nibiru/Resources-and-Repo-Configs-b31aa8074a2b419d80b0c946ed5efab0
       DEVNET_NUMBER: ${{ secrets.DEVNET_NUMBER }}
       VALIDATOR_MNEMONIC: ${{ secrets.VALIDATOR_MNEMONIC }}
+      EXAMPLES_WALLET_MNEMONIC: ${{ secrets.EXAMPLES_WALLET_MNEMONIC }}
     steps:
       # ----------------------------------------------
       # check-out repo and set-up python
@@ -99,9 +100,9 @@ jobs:
           cd examples
           for filename in *; do
             if [[ $filename == *.ipynb ]] ; then
-              if [ $filename != "3- Arbitrage.ipynb" ] && [ $filename != "colab_notebook.ipynb" ]; then
-                jupyter nbconvert --to python "$filename"
-              fi
+              sed -i '/pip install nibiru/d' "$filename"
+              sed -i "s/put your mnemonic here.../$EXAMPLES_WALLET_MNEMONIC/g" "$filename"
+              jupyter nbconvert --to python "$filename"
             fi
           for filename in *; do
             if [[ $filename == *.py ]]; then

diff --git a/README.md b/README.md
@@ -34,18 +34,6 @@ 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.
 
-## Try running nibiru sdk online
-
-Open the google collab link below to try running Niburu code online: 
-
-<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+
@@ -59,19 +47,16 @@ pip install nibiru  # requires Python 3.8+
 import json
 from nibiru import Network, ChainClient
 
-client = ChainClient(Network.testnet(2))
+client = ChainClient(Network.testnet(3))
 
 # Query perp markets
-print(json.dumps(client.query.perp.markets(), indent=4))
+perp_markets = client.query.perp.markets()
+print(json.dumps(perp_markets, indent=4))
 
 # Query trader's positions
-print(
-  json.dumps(
-    client.query.perp.all_positions(
-      trader="nibi1jle8khj3aennq24zx6g93aam9rt0fqhgyp4h52"
-    ),
-    indent=4)
-)
+trader_addr = "nibi1jle8khj3aennq24zx6g93aam9rt0fqhgyp4h52"
+positions = client.query.perp.all_positions(trader=trader_addr)
+print(json.dumps(positions, indent=4))
 ```
 
 ### Submitting transactions to the chain
@@ -104,7 +89,7 @@ Use faucet to get some test tokens into your wallet: https://app.nibiru.fi/fauce
 
 ```python
 mnemonic = "put your mnemonic here..."
-client = ChainClient(network=Network.testnet(2))
+client = ChainClient(network=Network.testnet(3))
 client.authenticate(mnemonic=mnemonic)
 print(client.address)
 ```
@@ -124,19 +109,29 @@ output = client.tx.execute_msgs(
     is_long=True,
     margin=10,
     leverage=2,
-  )
+  ),
+  wait_for_tx_resp=True,  # wait for block and get tx response
 )
 print(output)
 ```
 
 You can broadcast any available transaction by passing its corresponding `Msg` to the `client.tx.execute_msgs` function.
 
-## Documentation Website
+## Nibiru SDK By Example
+
+The [examples folder](examples) folder contains jupyter notebooks for a quick introduction with example to the nibiru python sdk. The goal is to teach how to query and interact with any chain (testnet, localnet, mainnet).
+
+All the examples are available for running online in Google Colab.
+
 
-Documentation can be found here: [Nibiru-py documentation](https://nibiru-py.readthedocs.io/en/latest/index.html)
+| Local                                       | Google Colab |
+|---------------------------------------------|--------------|
+| [Quick start](examples/1_quick_start.ipynb) | [![Open in collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NibiruChain/py-sdk/blob/main/examples/1_quick_start.ipynb) |
+| [Bank](examples/2_bank.ipynb)               | [![Open in collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NibiruChain/py-sdk/blob/main/examples/2_bank.ipynb) |
+| [Perpetuals](examples/3_perp.ipynb)         | [![Open in collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NibiruChain/py-sdk/blob/main/examples/3_perp.ipynb) |
+| [Spots](examples/4_spot.ipynb)              | [![Open in collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NibiruChain/py-sdk/blob/main/examples/4_spot.ipynb) |
+| [Staking](examples/5_staking.ipynb)         | [![Open in collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NibiruChain/py-sdk/blob/main/examples/5_staking.ipynb) |
 
-- Learn more about opening and managing your spot and perp positions [here](https://nibiru-py.readthedocs.io/en/latest/nibiru.sdks.tx.html#nibiru-sdks-tx-package)
-- Learn about querying the chain using the Sdk [here](https://nibiru-py.readthedocs.io/en/latest/nibiru.clients.html#nibiru-clients-package)
 
 ## Contributing
 

diff --git a/...s/1- Connect to nibiru py and query.ipynb → examples/1_quick_start.ipynb b/...s/1- Connect to nibiru py and query.ipynb → examples/1_quick_start.ipynb
@@ -1,54 +1,63 @@
 {
  "cells": [
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "attachments": {},
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "import nibiru\n",
-    "from nibiru import Network, ChainClient\n",
-    "import json"
+    "# Connect to Nibiru Chain and Run Queries"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### 1. Install Nibiru package"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
    "outputs": [],
    "source": [
-    "nibiru.__version__"
-   ]
+    "!pip install nibiru"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
-   "metadata": {},
    "source": [
-    "# Connect to a chain and run queries"
-   ]
-  },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "You can connect to any chain (localnet, testnet or mainnet) using this python SDK. Let's connect to testnet-2 (aka itn-2)."
-   ]
+    "### 2. Create chain client\n",
+    "Using testnet-3 (aka itn-3) endpoint run queries."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "client = ChainClient(Network.testnet(2))"
+    "from nibiru import Network, ChainClient\n",
+    "import json\n",
+    "\n",
+    "# Shortcut to print responses\n",
+    "def print_json(obj):\n",
+    "    print(json.dumps(obj, indent=2))\n",
+    "\n",
+    "client = ChainClient(Network.testnet(3))"
    ]
   },
   {
    "cell_type": "markdown",
    "source": [
-    "Run PERP module queries:"
+    "### 3. Run PERP module queries"
    ],
    "metadata": {
     "collapsed": false
@@ -59,7 +68,8 @@
    "execution_count": null,
    "outputs": [],
    "source": [
-    "print(json.dumps(client.query.perp.markets(), indent=4))"
+    "perp_markets = client.query.perp.markets()\n",
+    "print_json(perp_markets)"
    ],
    "metadata": {
     "collapsed": false
@@ -70,7 +80,10 @@
    "execution_count": null,
    "outputs": [],
    "source": [
-    "print(json.dumps(client.query.perp.all_positions(trader=\"nibi1jle8khj3aennq24zx6g93aam9rt0fqhgyp4h52\"), indent=4))"
+    "# Query perp positions of the trader\n",
+    "trader = \"nibi1jle8khj3aennq24zx6g93aam9rt0fqhgyp4h52\"\n",
+    "positions = client.query.perp.all_positions(trader=trader)\n",
+    "print_json(positions)"
    ],
    "metadata": {
     "collapsed": false
@@ -79,7 +92,7 @@
   {
    "cell_type": "markdown",
    "source": [
-    "Run SPOT module queries:"
+    "### 4. Run SPOT module queries"
    ],
    "metadata": {
     "collapsed": false
@@ -91,7 +104,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(json.dumps(client.query.spot.pools(), indent=4))"
+    "spot_pools = client.query.spot.pools()\n",
+    "print_json(spot_pools)"
    ]
   },
   {
@@ -100,31 +114,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(json.dumps(client.query.spot.total_pool_liquidity(1), indent=4))"
+    "pool_liquidity = client.query.spot.total_pool_liquidity(1)\n",
+    "print(pool_liquidity)"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "print(json.dumps(client.query.spot.total_liquidity(), indent=4))"
-   ]
-  },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "You can find the documentation on query you can execute on the official documentation website: https://nibiru-py.readthedocs.io/en/latest/nibiru.query_clients.html"
-   ]
-  },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": []
   }
  ],
  "metadata": {