Skip to content

Commit 85e72b0

Browse files
gaonipgaonip
committed
Add revshare and update docs feedback
1 parent f51d4ae commit 85e72b0

File tree

5 files changed

+173
-3
lines changed

5 files changed

+173
-3
lines changed

‎vocs-docs/docs/pages/concepts/trading/isolated-positions.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,17 @@ parent subaccount 1 has child subaccounts 129, 257,...
2727
parent_subaccount_number = child_subaccount_number % 128
2828
```
2929

30-
> Note that currently only parent subaccount 0 is exposed via the frontend and so isolated positions will be held in subaccounts number 128, 256, ...
30+
:::note
31+
Note that currently only parent subaccount 0 is exposed via the frontend and so isolated positions will be held in subaccounts number 128, 256, ...
32+
:::
33+
34+
:::note
35+
Note that the above "types" of subaccounts are not enforced at a protocol level, and only on the frontend. Any subaccount can hold any number of positions in cross-marginable markets which all will cross-margined at the protocol level.
36+
:::
3137

32-
> Note that the above "types" of subaccounts are not enforced at a protocol level, and only on the frontend. Any subaccount can hold any number of positions in cross-marginable markets which all will cross-margined at the protocol level.
38+
:::note
39+
When you are using the dYdX frontend, any margin transferred to an empty child subaccount that isn’t used for placing a trade will get sent back to the cross subaccount after some time.
40+
:::
3341

3442
## Getting data for parent subaccount
3543

‎vocs-docs/docs/pages/interaction/data/market.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,10 @@ See the [API reference](/indexer-client/http/markets/get_perpetual_markets) for
9292

9393
Retrieve orders for a specific subaccount, with various filtering options to narrow down the results based on order characteristics.
9494

95+
:::info
96+
It is recommended to set specific clientID's when placing different orders, which will be useful to retrieve back a specific order on the `v4/orders` endpoint
97+
:::
98+
9599
:::code-group
96100

97101
```python [Python]

‎vocs-docs/docs/pages/interaction/integration/integration-onboarding.mdx‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,47 @@
11
# Onboarding
22

33
## dYdX address
4-
The client application onboards the user by asking the user to sign a message using an existing wallet address. The v4-client-js library provides a [function](https://github.com/dydxprotocol/v4-clients/blob/a2c7adcc64b33fefaf56ffb6fc1d2bb8b174601e/v4-client-js/src/lib/onboarding.ts#L43) that deterministically generates the dYdX chain address and keys from the signed message.
4+
The client application onboards the user by asking the user to sign a message using an existing wallet address. The v4-client-js library provides a [function](https://github.com/dydxprotocol/v4-clients/blob/a2c7adcc64b33fefaf56ffb6fc1d2bb8b174601e/v4-client-js/src/lib/onboarding.ts#L43) that deterministically generates the dYdX chain address (see [accounts](/concepts/trading/accounts#main-account)) and keys from the signed message.
55
Once the keys are generated, the client application can use them to sign transactions on the dYdX chain on the user’s behalf, enabling secure and seamless interaction with the platform.
66

7+
The payload doesn't matter to generate a dYdX address, but if you want to deterministically generate a dYdX address that matches what the dYdX Frontend generates, it is best to have the same payload message
8+
```json
9+
10+
"message": {
11+
"action": "dYdX Chain Onboarding"
12+
}
13+
14+
```
15+
16+
The payload typically looks like this:
17+
18+
:::details
19+
```ts
20+
const ethersWallet = new ethers.Wallet('<wallet>');
21+
const provider = new JsonRpcProvider('https://ethereum.publicnode.com', 1);
22+
const signer = ethersWallet.connect(provider);
23+
24+
const signature = await signer.signTypedData(
25+
{
26+
name: 'dYdX Chain',
27+
chainId: 1,
28+
},
29+
{
30+
dYdX: [{ name: 'action', type: 'string' }],
31+
},
32+
{
33+
action: 'dYdX Chain Onboarding',
34+
},
35+
);
36+
37+
const { mnemonic, privateKey, publicKey } = deriveHDKeyFromEthereumSignature(signature);
38+
```
39+
:::details
40+
41+
### Subaccounts
42+
Each main account has 128,001 [subaccounts](/concepts/trading/accounts#subaccounts)
43+
Subaccounts 0 to 127 are parent subaccounts. Parent subaccounts can have multiple positions opened and all positions are cross-margined.
44+
Subaccounts 128 to 128,000 are child subaccounts and are isolated margin. Child subaccounts will only ever have up to 1 position open.
745

846
## Deposits and Withdrawals
947

‎vocs-docs/docs/pages/interaction/integration/integration-revshare.mdx‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Revenue Share
2+
3+
rder Router Rev Share enables third-party order routers to direct orders to dYdX and earn a portion of the trading fees (maker and taker). The revenue share, specified in parts per million (ppm), must be voted in via Governance and set in the `order_router_address` field in the order message itself.
4+
5+
The revenue will be distributed based on filled orders that were routed through the participating order router.
6+
7+
Order router details and revenue share percentages can be monitored through the indexer using the `/orders` and `/fills` endpoints. The `/orders` endpoint provides information on the order router address, while the `/fills` endpoint shows the order router address and the specific revenue amount distributed per fill.
8+
9+
To participate in the Order Router Rev Share program, users need to propose and have a passing vote for their order router address & revenue split.
10+
11+
- The maximum revenue share allowed is `800,000` ppm (80% of trading fees).
12+
- Affiliate revenue takes priority in the distribution hierarchy.
13+
- If there is an active affiliate split that has not reached its maximum within a 30-day rolling window, no revenue will be shared with the order router
14+
15+
## Implementation Details
16+
17+
::::steps
18+
19+
## Voting in via Governance
20+
21+
To participate in the Order Router Rev Share program, you need to create and submit a governance proposal. Below is an example of what the governance message structure looks like:
22+
```json
23+
message Order {
24+
"messages": [
25+
{
26+
"@type": "/dydxprotocol.revshare.MsgSetOrderRouterRevShare",
27+
"authority": authority,
28+
"order_router_rev_share": {
29+
"address": {{your address}},
30+
"sharePpm": {{your requested ppm}},
31+
}
32+
}
33+
]
34+
}
35+
```
36+
The key components of this message are:
37+
38+
- `address` - The address of the order router that will receive the revenue share. This is also the id you place in your order message
39+
- `sharePpm` - The revenue share percentage in parts per million (ppm). This should be between `[0, 800,000)` ppm
40+
41+
After submitting the proposal, it must go through the standard governance voting process and receive a passing vote before the order router address and revenue share percentage are activated in the system.
42+
43+
## Updating Revenue Share (Optional)
44+
45+
The process for updating an existing order router's revenue share is the same as setting up a new one. You will need to submit a governance proposal with the updated parameters.
46+
47+
To update the revenue share percentage for an existing order router, create a governance message with the same structure:
48+
49+
```json
50+
"messages": [
51+
{
52+
"@type": "/dydxprotocol.revshare.MsgSetOrderRouterRevShare",
53+
"authority": authority,
54+
"order_router_rev_share": {
55+
"address": {{your existing address}},
56+
"sharePpm": {{your new requested ppm}},
57+
}
58+
}
59+
]
60+
```
61+
62+
The proposal must go through the standard governance voting process and receive a passing vote before the updated revenue share percentage takes effect.
63+
64+
Note that:
65+
66+
- The updated sharePpm must still be within the allowable range of `[0, 800,000)` ppm
67+
- You must use the exact same address that was previously approved
68+
- The update will completely replace the previous configuration once approved
69+
70+
## Deleting an Order Router Rev Share (Optional)
71+
72+
To delete an order router's revenue share configuration, you simply need to set the revenue share percentage to 0. This process follows the same governance workflow as setting up or updating a revenue share.
73+
74+
Submit a governance proposal with the following message structure:
75+
```json
76+
"messages": [
77+
{
78+
"@type": "/dydxprotocol.revshare.MsgSetOrderRouterRevShare",
79+
"authority": authority,
80+
"order_router_rev_share": {
81+
"address": {{your existing address}},
82+
"sharePpm": 0,
83+
}
84+
}
85+
]
86+
```
87+
88+
Key points to note:
89+
90+
- Setting `sharePpm` to 0 effectively disables the revenue share for that order router
91+
- The address must match the previously approved order router address
92+
- The proposal must still pass through the standard governance voting process
93+
- Once approved, the order router will no longer receive any revenue share
94+
95+
After the proposal passes, any orders that include this order router address will no longer generate revenue share for the router.
96+
97+
## Changes to the Order Message
98+
The `order_router_address` field is set when an order is placed
99+
100+
- `order_router_address` - the ID of the order router and where fees will be sent to
101+
102+
```go
103+
message Order {
104+
// The unique ID of this order. Meant to be unique across all orders.
105+
OrderId order_id = 1 [ (gogoproto.nullable) = false ];
106+
...
107+
// order_router_address is the metadata for the frontend order router.
108+
string order_router_address = 13;
109+
}
110+
```
111+
112+
## Order Validation Checks
113+
114+
- Ensure the `order_router_address` field is valid and already voted in via governance
115+
116+
::::

‎vocs-docs/docs/pages/interaction/trading/index.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,10 @@ Every order created has an unique identifier, referred to as the __order ID__. I
5656
- **Order flags**: An integer identifying if the order is short-term (`0`), long-term (`64`), or conditional (`32`);
5757
- **CLOB Pair ID**: The ID of the underlying market/perpetual.
5858

59+
:::info
60+
It is recommended to set specific clientID's when placing different orders, which will be useful to retrieve back a specific order on the `v4/orders` endpoint
61+
:::
62+
5963
:::code-group
6064

6165
```python [Python]

0 commit comments

Comments
 (0)