From 2c92dc277c4297c30319b72b5072fe59ced8902e Mon Sep 17 00:00:00 2001
From: samtin0x <40127309+samtin0x@users.noreply.github.com>
Date: Fri, 18 Oct 2024 16:47:17 +0200
Subject: [PATCH] chore: Update v2 docs (#239)

---
 .../documentation/account_details.md          | 26 ++++-
 .../documentation/network_setup.md            | 94 ++++++++++++++-----
 v4-client-py-v2/dydx_v4_client/network.py     |  9 ++
 3 files changed, 102 insertions(+), 27 deletions(-)

diff --git a/v4-client-py-v2/documentation/account_details.md b/v4-client-py-v2/documentation/account_details.md
index beb2b158..0da770a4 100644
--- a/v4-client-py-v2/documentation/account_details.md
+++ b/v4-client-py-v2/documentation/account_details.md
@@ -1,6 +1,26 @@
-# Getting Account Order Information
+# Getting Account and Subaccount Information
 
-This guide demonstrates how to retrieve information about your account's orders using the dYdX Python SDK.
+This guide demonstrates how to retrieve information about your account, subaccounts, and orders using the dYdX Python SDK.
+
+## Understanding Accounts and Subaccounts
+
+**Accounts**
+- Your primary identity on dYdX, linked to your blockchain wallet address.
+- Acts as a container for all your trading activities and subaccounts.
+
+**Subaccounts**
+- Separate trading entities within your main account.
+- Each has its own balance, positions, orders, and trading history.
+- Every account starts with subaccount 0; additional subaccounts can be created.
+
+**Key Points**
+- Subaccounts allow segregation of trading strategies and risk management.
+- Losses in one subaccount don't affect others.
+- Useful for separating personal trading, algorithms, or different fund allocations.
+
+**API Usage**
+- Most operations require both the account address and subaccount number.
+- Example: `get_subaccount_orders(address, subaccount_number)`
 
 ## Setting Up
 
@@ -23,7 +43,7 @@ To retrieve all open orders for an account:
 async def get_open_orders(address):
     orders = await client.account.get_subaccount_orders(
         address,
-        0,
+        0, # Subaccount ID
         status="OPEN"
     )
     print("Open orders:", orders)
diff --git a/v4-client-py-v2/documentation/network_setup.md b/v4-client-py-v2/documentation/network_setup.md
index ac40e9e1..143ba35a 100644
--- a/v4-client-py-v2/documentation/network_setup.md
+++ b/v4-client-py-v2/documentation/network_setup.md
@@ -1,56 +1,102 @@
 ### Networks
 
-> **See [network resources](https://docs.dydx.exchange/infrastructure_providers-network/resources#networks-repositories) to find publicly available endpoints**
+This guide explains how to connect to different dYdX networks using the Python SDK.
+
+#### Finding Network Endpoints
+
+> **Important:** For the most up-to-date list of publicly available endpoints, refer to our [network resources documentation](https://docs.dydx.exchange/infrastructure_providers-network/resources#networks-repositories).
+
+#### Connecting to Mainnet
+
+To connect to the mainnet, use the `make_mainnet` function:
 
-To connect to the mainnet you can use `make_mainnet` function:
 ```python
 from dydx_v4_client.network import make_mainnet
 
-
 NETWORK = make_mainnet(
-    node_url=NODE_URL, 
-    rest_indexer=REST_URL, 
-    websocket_indexer=WEBSOCKET_URL
+    node_url="NODE_URL",  # No 'https://' prefix
+    rest_indexer="REST_INDEXER_URL",
+    websocket_indexer="WEBSOCKET_INDEXER_URL"
 )
 ```
 
-For local and testnet networks there is a set of predefined networks:
+> Note the above are just an example of the mainnet endpoints. Always use the most recent endpoints from our [network resources documentation](https://docs.dydx.exchange/infrastructure_providers-network/resources#indexer-endpoints).
+
+⚠️ **Important:** When specifying `node_url`, do not include the `https://` prefix. This is a common mistake that can cause connection issues.
+
+#### Connecting to Testnet
+
+For testnet, you can use the predefined `TESTNET` network:
 
 ```python
-from dydx_v4_client.network import TESTNET, LOCAL
+from dydx_v4_client.network import TESTNET
+
+# Use TESTNET directly in your client initialization
 ```
 
-If you want to use a custom API each network has its respective _make_ function:
+To customize the testnet connection:
+
 ```python
-from dydx_v4_client.network import make_testnet, make_local
+from dydx_v4_client.network import make_testnet
+
+CUSTOM_TESTNET = make_testnet(
+    node_url="your-custom-testnet-node-url",
+    rest_indexer="your-custom-testnet-rest-url",
+    websocket_indexer="your-custom-testnet-websocket-url"
+)
 ```
 
-You can overwrite the default URL when calling the function:
+> Find the latest testnet endpoints in our [network resources documentation](https://docs.dydx.exchange/infrastructure_providers-network/resources#networks-repositories).
+
+#### Local Development
+
+For local development, use the predefined `LOCAL` network:
+
 ```python
-NETWORK = make_local(node_url="http://localhost:26657")
+from dydx_v4_client.network import LOCAL
+
+# Use LOCAL directly in your client initialization
 ```
 
-To create a custom network you can do it directly:
+To customize the local network:
+
 ```python
-from dydx_v4_client.network import Network, NodeConfig, secure_channel
+from dydx_v4_client.network import make_local
+
+CUSTOM_LOCAL = make_local(node_url="http://localhost:26657")
+```
+
+#### Creating a Custom Network
+
+For advanced users who need to define a completely custom network:
 
+```python
+from dydx_v4_client.network import Network, NodeConfig, secure_channel
 
-CUSTOM_MAINNET = Network(
-    "https://dydx-testnet.imperator.co",
-    "wss://indexer.v4testnet.dydx.exchange/v4/ws",
+CUSTOM_NETWORK = Network(
+    "https://your-custom-rest-url.com",
+    "wss://your-custom-websocket-url.com/ws",
     NodeConfig(
-        "dydx-testnet-4",
-        secure_channel("test-dydx-grpc.kingnodes.com"),
-        "adv4tnt",
-        "ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5",
-    ),
+     "dydx-testnet-4",
+     secure_channel("test-dydx-grpc.kingnodes.com"),
+     "adv4tnt",
+     "ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5",
+     ),
 )
 ```
-Or provide the URL directly to the client, e.g.:
+
+#### Direct URL Usage
+
+You can also provide URLs directly to specific clients:
+
 ```python
-indexer = IndexerClient("https://dydx-testnet.imperator.co")
+from dydx_v4_client import IndexerClient
+
+indexer = IndexerClient("https://your-indexer-url.com")
 ```
 
+Remember to always use the most recent endpoints from our [network resources documentation](https://docs.dydx.exchange/infrastructure_providers-network/resources#networks-repositories) when connecting to dYdX networks.
+
 #### Using Non-SSL Connections
 The SDK supports both secure (SSL) and insecure (non-SSL) connections. By default, secure connections are used. However, for scenarios where you need to use a non-SSL node (e.g., local development), you can use the make_insecure function:
 
diff --git a/v4-client-py-v2/dydx_v4_client/network.py b/v4-client-py-v2/dydx_v4_client/network.py
index ce0232e6..f8ec09c3 100644
--- a/v4-client-py-v2/dydx_v4_client/network.py
+++ b/v4-client-py-v2/dydx_v4_client/network.py
@@ -1,9 +1,12 @@
+import logging
 from dataclasses import dataclass
 from functools import partial
 
 import grpc
 from grpc import insecure_channel
 
+logger = logging.getLogger(__name__)
+
 secure_channel = partial(
     grpc.secure_channel, credentials=grpc.ssl_channel_credentials()
 )
@@ -27,6 +30,12 @@ class Network:
 def make_config(
     make_channel, make_node, rest_indexer: str, websocket_indexer: str, node_url: str
 ):
+    if node_url.startswith("http://") or node_url.startswith("https://"):
+        logger.warning(
+            "Node URL should not contain http(s)://. Stripping the prefix. In the future, consider providing the URL without the http(s) prefix."
+        )
+        node_url = node_url.split("://", 1)[1]
+
     return Network(
         rest_indexer,
         websocket_indexer,