diff --git a/docs.renegade.fi/docs/technical-reference/_category_.json b/docs.renegade.fi/docs/technical-reference/_category_.json new file mode 100644 index 00000000..8a5fee37 --- /dev/null +++ b/docs.renegade.fi/docs/technical-reference/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Technical Reference", + "position": 4 +} diff --git a/docs.renegade.fi/docs/typescript-sdk/getting-started.md b/docs.renegade.fi/docs/technical-reference/typescript-sdk.md similarity index 61% rename from docs.renegade.fi/docs/typescript-sdk/getting-started.md rename to docs.renegade.fi/docs/technical-reference/typescript-sdk.md index 54c0c9a4..7be46637 100644 --- a/docs.renegade.fi/docs/typescript-sdk/getting-started.md +++ b/docs.renegade.fi/docs/technical-reference/typescript-sdk.md @@ -12,18 +12,28 @@ To add the Renegade SDK to your project, install the required packages. ```bash npm install @renegade-fi/node@latest @wagmi/core viem@2.x ``` + +This SDK is responsible for interacting with a relayer. Some actions, such as `createWallet` or `deposit`, require using your Ethereum wallet to sign messages or approve tokens. To perform these actions, we recommend using [wagmi](https://wagmi.sh/core/getting-started) and [viem](https://viem.sh/docs/getting-started). + ### Create Config -Create and export a new Renegade config using `createConfig`. +Create and export a new Renegade config using `createConfig`. ```jsx import { createConfig } from "@renegade-fi/node" +import { createPublicClient, http } from 'viem' +import { arbitrum } from 'viem/chains' + +const viemClient = createPublicClient({ + chain: arbitrum, + transport: http() +}) export const config = createConfig({ darkPoolAddress: "0x30bd8eab29181f790d7e495786d4b96d7afdc518", priceReporterUrl: "mainnet.price-reporter.renegade.fi", relayerUrl: "mainnet.cluster0.renegade.fi", - viemClient: publicClient, + viemClient, }) ``` @@ -33,63 +43,122 @@ Follow the instructions [here](https://viem.sh/docs/clients/public) to properly ::: +:::note + +`darkPoolAddress` is the address of the darkpool proxy contract, **not** the implementation contract itself. You can find the darkpool proxy address for your environment [here](../technical-reference/contract-addresses.md). + +::: + ### Use the SDK Now, you can pass the `config` to use actions. ```jsx import { backOfQueueWallet } from "@renegade-fi/node" -import { createConfig } from "@renegade-fi/node" - -const config = createConfig({ - darkPoolAddress: "0x30bd8eab29181f790d7e495786d4b96d7afdc518", - priceReporterUrl: "mainnet.price-reporter.renegade.fi", - relayerUrl: "mainnet.cluster0.renegade.fi", - viemClient: publicClient, -}) const wallet = await getBackOfQueueWallet(config) + +console.log("Wallet balances: ", wallet.balances) ``` ### Environment Setup :::note -You must expose a `TOKEN_MAPPING` environment variable to use the SDK. You can do so by adding a `.env` file in the root of your project. See this [repo](https://stackblitz.com/edit/nodets-bnycf1?file=.env.example&view=editor) for an example. +You must expose a `TOKEN_MAPPING` environment variable to use the SDK. You can do so by adding a `.env` file in the root of your project. See this [repo](https://stackblitz.com/edit/nodets-bnycf1?file=.env.example&view=editor) for an example. You can find the token mapping for your environment [here](../technical-reference/useful-addresses.md). ::: -- Node Version - - We recommend using Node v22 - - Typescript config - - Take a look at this [example repo](https://stackblitz.com/edit/nodets-bnycf1?file=tsconfig.json&view=editor) for a reference `tsconfig.json`. - - -- Helpful values to know - - Mainnet (Arbitrum One) - - Darkpool contract address: `0x30bd8eab29181f790d7e495786d4b96d7afdc518` - - Permit2 contract address: `0x000000000022D473030F116dDEE9F6B43aC78BA3` - - Chain ID: `42161` - - Chain name: `Arbitrum One` - - Chain RPC URL: [`https://arb1.arbitrum.io/rpc`](https://arb1.arbitrum.io/rpc) - - You should use your own Alchemy / Infura RPC url here instead - - Token mapping: download JSON [here](https://github.com/renegade-fi/token-mappings/raw/main/mainnet.json) - - Renegade Price Reporter: [`mainnet.price-reporter.renegade.fi`](http://mainnet.price-reporter.renegade.fi/) - - Renegade Relayer: [`mainnet.cluster0.renegade.fi`](http://mainnet.cluster0.renegade.fi/) - - Testnet (Arbitrum Sepolia) - - Darkpool contract address: `0x9af58f1ff20ab22e819e40b57ffd784d115a9ef5` - - Permit2 contract address: `0x9458198bcc289c42e460cb8ca143e5854f734442` - - Chain ID: `421614` - - Chain name: `Arbitrum Sepolia` - - Chain RPC URL: [`https://sepolia-rollup.arbitrum.io/rpc`](https://sepolia-rollup.arbitrum.io/rpc) - - You should use your own Alchemy / Infura RPC url here instead - - Token mapping: download JSON [here](https://github.com/renegade-fi/token-mappings/raw/main/testnet.json) - - Renegade Price Reporter: [`testnet.price-reporter.renegade.fi`](http://testnet.price-reporter.renegade.fi/) - - Renegade Relayer: [`testnet.cluster0.renegade.fi`](http://testnet.cluster0.renegade.fi/) +We recommend using Node v22 as it [provides a WebSocket client to Node.js](https://nodejs.org/en/blog/announcements/v22-release-announce#websocket) without external dependencies. If you are on a lower version of Node, you should provide your own WebSocket client, such as `ws`. + +This SDK makes exclusive use of ES Modules. Check out [this guide](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) for more info on ESM support and Frequently Asked Questions across various tools and setups. + +For Typescript configuration, check out this [example repo](https://stackblitz.com/edit/nodets-bnycf1?file=tsconfig.json&view=editor) for a reference `tsconfig.json`. + +## Protocol Core Concepts + +### Relayer +A relayer node is resposible for the matching and settlement of orders. Each individual relayer manages one or more wallets, meaning they are able to view the plaintext wallet but are unable to modify a wallet. In order to modify a wallet (placing orders, depositing assets, etc.), users sign updates to their wallet state and queue asynchronous “tasks” in the relayer. + +:::note +Relayers manage task queues for each wallet, which means you do not necessarily need to wait for a task to complete before creating a new task. This is why two functions exist for fetching a wallet's state: [`getWalletFromRelayer`](#getwalletfromrelayer) (current wallet state) and [`getBackOfQueueWallet`](#getbackofqueuewallet) (wallet state after current task queue is cleared). +::: + +### Wallet +A wallet is a data structure that contains a user's balances, orders, and keys. To create a wallet, you must sign a message using your Ethereum wallet to generate a derivation key. This derivation key is used to derive the required fields of a wallet, such as the keychain. Learn more about keychains [here](../advanced-concepts/super-relayers.md). + +## SDK Core Concepts + +### Config +The `Config` object is responsible for storing Renegade wallet state and internals. Most actions require a `Config` object to be passed as the first argument, as it contains the derivation key used to derive keys used to sign API requests and wallet updates. + +### Actions +This SDK exposes actions that are used to interact with a relayer, such as fetching a wallet's state or placing an order. Actions that access private wallet data require API authorization headers, which are automatically added for you when using the SDK. Browse the list of available actions [below](#actions-1). + +### Types +This SDK provides types for various data structures used in the API. + +- [`Wallet`](https://github.com/renegade-fi/typescript-sdk/blob/bd7455916d3b69f35511337e2cf6b681247dd654/packages/core/src/types/wallet.ts#L34): contains a user's balances, orders, and keys +- [`Order`](https://github.com/renegade-fi/typescript-sdk/blob/bd7455916d3b69f35511337e2cf6b681247dd654/packages/core/src/types/order.ts#L1): contains an order's parameters +- [`Balance`](https://github.com/renegade-fi/typescript-sdk/blob/bd7455916d3b69f35511337e2cf6b681247dd654/packages/core/src/types/wallet.ts#L15): contains the amount of an ERC-20 token a user has in addition to the fee amount owed for that token. +- [`KeyChain`](https://github.com/renegade-fi/typescript-sdk/blob/bd7455916d3b69f35511337e2cf6b681247dd654/packages/core/src/types/wallet.ts#L22): contains a user's key hierarchy as defined [here](../advanced-concepts/super-relayers.md). +- [`OrderMetadata`](https://github.com/renegade-fi/typescript-sdk/blob/bd7455916d3b69f35511337e2cf6b681247dd654/packages/core/src/types/order.ts#L19): contains useful metadata such as the order's ID, status, creation time, and [`PartialOrderFills`](https://github.com/renegade-fi/typescript-sdk/blob/bd7455916d3b69f35511337e2cf6b681247dd654/packages/core/src/types/order.ts#L27) since creation. +- [`Task`](https://github.com/renegade-fi/typescript-sdk/blob/bd7455916d3b69f35511337e2cf6b681247dd654/packages/core/src/types/task.ts#L1): contains a task's ID, status, type, and creation time. + +### Token + +The `Token` class is used to store ERC-20 token metadata. It encapsulates information such as the token's address, name, decimals, and ticker symbol. This metadata is sourced from the `TOKEN_MAPPING` defined in your `.env` file. + +**Import** + +```js +import { Token } from "@renegade-fi/node" +``` + +**Properties** + +- `address`: The address of the ERC-20 token. +- `name`: The name of the token. +- `decimals`: The number of decimals the token uses. +- `ticker`: The ticker symbol of the token. + +**Static Methods** +```js +static findByTicker(ticker: string): Token +``` +**Returns** +- `Token` - The Token instance matching the given ticker. + +**Throws** +- `Error` - If no token with the given ticker is found in the TOKEN_MAPPING. + +```js +static findByAddress(address: `0x${string}`): Token +``` +**Returns** +- `Token` - The Token instance matching the given address. + +**Throws** +- `Error` - If no token with the given address is found in the TOKEN_MAPPING. + + +**Usage** + +```jsx +import { Token } from "@renegade-fi/node" + +const usdc = Token.findByTicker("USDC") + +console.log("USDC address: ", usdc.address) + +const weth = Token.findByAddress("0xaf88d065e77c8cc2239327c5edb3a432268e5831") + +console.log("WETH address: ", weth.address) +``` ## Configuration -### `createConfig` +### createConfig **Import** @@ -140,7 +209,7 @@ import { type Config } from '@renegade-fi/node' ## Actions -### `createWallet` +### createWallet Action for starting a `create wallet` task on your connected relayer. @@ -153,23 +222,10 @@ import { createWallet } from "@renegade-fi/node" **Usage** ```jsx -import { createConfig, createWallet, ROOT_KEY_MESSAGE_PREFIX, } from "@renegade-fi/node" +import { createWallet, ROOT_KEY_MESSAGE_PREFIX } from "@renegade-fi/node" import { privateKeyToAccount } from "viem/accounts" -import { createPublicClient, http } from "viem" import { arbitrum } from "viem/chains" -const publicClient = createPublicClient({ - chain: arbitrum, - transport: http() -}) - -export const config = createConfig({ - darkPoolAddress: "0x30bd8eab29181f790d7e495786d4b96d7afdc518", - priceReporterUrl: "mainnet.price-reporter.renegade.fi", - relayerUrl: "mainnet.cluster0.renegade.fi", - viemClient: publicClient, -}) - const account = privateKeyToAccount('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80') const seed = await account.signMessage({ @@ -194,7 +250,7 @@ An error may be thrown if: - a `seed` does not exist in the provided `config` - a wallet with the same wallet ID already exists in the state of the connected relayer -### `lookupWallet` +### lookupWallet Action for starting a `lookup wallet` task on your connected relayer. @@ -207,22 +263,9 @@ import { lookupWallet } from "@renegade-fi/node" **Usage** ```jsx -import { createConfig, lookupWallet } from "@renegade-fi/node" -import { createPublicClient, http } from "viem" +import { lookupWallet } from "@renegade-fi/node" import { arbitrum } from "viem/chains" -const publicClient = createPublicClient({ - chain: arbitrum, - transport: http() -}) - -export const config = createConfig({ - darkPoolAddress: "0x30bd8eab29181f790d7e495786d4b96d7afdc518", - priceReporterUrl: "mainnet.price-reporter.renegade.fi", - relayerUrl: "mainnet.cluster0.renegade.fi", - viemClient: publicClient, -}) - config.setState((x) => ({ ...x, seed })) await lookupWallet(config).then(() => console.log('Finished looking up wallet')) @@ -242,7 +285,7 @@ An error may be thrown if: - a wallet with the same wallet ID already exists in the state of the connected relayer - a wallet was not able to be found on-chain -### `getWalletFromRelayer` +### getWalletFromRelayer Action for fetching a wallet’s state from your connected relayer. @@ -266,17 +309,19 @@ console.log("Wallet balances: ", wallet.balances) **Error** -An error may be thrown if +An error may be thrown if: - a `seed` does not exist in the provided `config` - the wallet is not currently indexed by your connected relayer, in which case you should `createWallet` or `lookupWallet` - the API request authorization is incorrect / missing -### `getBackOfQueueWallet` +### getBackOfQueueWallet Action for fetching the back of queue wallet state from your connected relayer. -> Your connected relayer will manage a queue of tasks for you. By fetching the back of queue wallet, you are fetching your wallet state *after* all tasks in the queue have completed. If a task fails, all subsequent tasks will transition to the `Failed` state and your queue will be cleared. +:::note +Your connected relayer will manage a queue of tasks for you. By fetching the back of queue wallet, you are fetching your wallet state *after* all tasks in the queue have completed, which may not be the case. If a task fails, all subsequent tasks will transition to the `Failed` state and your queue will be cleared. +::: **Import** @@ -298,19 +343,19 @@ console.log("Wallet balances: ", wallet.balances) **Error** -An error may be thrown if +An error may be thrown if: - a `seed` does not exist in the provided `config` - the wallet is not currently indexed by your connected relayer, in which case you should `createWallet` or `lookupWallet` - the API request authorization is incorrect / missing -### `deposit` +### deposit -Action for starting a `deposit` task on your connected relayer. +Action for starting a `deposit` task on your connected relayer. Transfers ERC-20 tokens from your Arbitrum address to your Renegade wallet. :::warning -You most likely want to use `executeDeposit` instead, as it will check for and execute ERC-20 allowances and permits as needed. +You most likely want to use [`executeDeposit`](#executedeposit) instead, as it will check for and execute ERC-20 allowances and permits as needed. ::: @@ -371,9 +416,9 @@ An error may be thrown if: - the Permit2 permit is incorrect / missing - the API request authorization is incorrect / missing -### `executeDeposit` +### executeDeposit -Action for starting a `deposit` task on your connected relayer, sending a transaction to approve the ERC-20 and signing a Permit2 `permit` if needed. +Action for starting a `deposit` task on your connected relayer, sending a transaction to approve the ERC-20 and signing a Permit2 `permit` if needed. Transfers ERC-20 tokens from your Arbitrum address to your Renegade wallet. **Import** @@ -386,9 +431,10 @@ import { executeDeposit } from "@renegade-fi/node" ```jsx import { createPublicClient, http } from "viem" import { arbitrum } from "viem/chains" -import { createConfig } from '@wagmi/core' +import { createConfig as createWagmiConfig } from '@wagmi/core' - const viemConfig = createConfig({ +// Wagmi config +const viemConfig = createWagmiConfig({ chains: [arbitrum], transports: { [arbitrum.id]: http(), @@ -451,13 +497,13 @@ An error may be thrown if: - the provided wagmi config is not configured properly - the API request authorization is incorrect / missing -### `withdraw` +### withdraw -Action for starting a `withdraw` task on your connected relayer. +Action for starting a `withdraw` task on your connected relayer. Transfers ERC-20 tokens from your Renegade wallet to your Arbitrum address. :::warning -You most likely want to use `executeWithdraw` instead, as it will check for and pay fees if needed. +You most likely want to use [`executeWithdrawal`](#executewithdrawal) instead, as it will check for and pay fees if needed. ::: @@ -506,9 +552,9 @@ An error may be thrown if: - there exist one or more balances with non-zero fees, meaning you must pay fees - the API request authorization is incorrect / missing -### `executeWithdrawal` +### executeWithdrawal -Action for starting a `withdraw` task on your connected relayer, paying fees if needed. +Action for starting a `withdraw` task on your connected relayer, paying fees if needed. Transfers ERC-20 tokens from your Renegade wallet to your Arbitrum address. **Import** @@ -557,10 +603,16 @@ An error may be thrown if: - the provided `amount` is less than the minimum transfer amount set by your connected relayer (currently 1 USDC) - the API request authorization is incorrect / missing -### `payFees` +### payFees Action for starting necessary `payFee` task(s) on your connected relayer. +:::warning + +You most likely will not invoke this function directly, as it is part of the [`executeWithdrawal`](#executewithdrawal) function. + +::: + **Import** ```jsx @@ -586,7 +638,7 @@ An error may be thrown if: - a `seed` does not exist in the provided `config` - the API request authorization is incorrect / missing -### `createOrder` +### createOrder Action for starting a `place order` task on your connected relayer. @@ -616,7 +668,7 @@ await createOrder(config, { - `0x${string}` - ERC-20 contract address of the quote asset (must be USDC). - side - - `“buy” | “sell”` + - `"buy" | "sell"` - The side this order is for **Return Type** @@ -627,12 +679,14 @@ Promise that resolves to the ID of the `place order` task in the connected relay **Error** +An error may be thrown if: + - a `seed` does not exist in the provided `config` - the provided `base` mint does not exist in the token mapping - the provided `quote` mint does not exist in the token mapping - the API request authorization is incorrect / missing -### `cancelOrder` +### cancelOrder Action for starting a `cancel wallet` task on your connected relayer. @@ -664,16 +718,28 @@ Promise that resolves to the ID of the `cancel order` task in the connected rela **Error** +An error may be thrown if: + - a `seed` does not exist in the provided `config` -- the provided `id` mint does not exist in the wallet’s list of orders +- the provided `id` mint does not exist in the wallet's list of orders - the API request authorization is incorrect / missing ## Examples -### Creating a wallet, placing and canceling an order +### Create a wallet + +- [Stackblitz Demo](https://stackblitz.com/edit/nodets-yppjgz?embed=1&file=src%2Fmain.ts&view=editor) + +### Place an order + +- [Stackblitz Demo](https://stackblitz.com/edit/nodets-sr1qf2?embed=1&file=src%2Fmain.ts&view=editor) + +### Cancel an order + +- [Stackblitz Demo](https://stackblitz.com/edit/nodets-fusaar?embed=1&file=src%2Fmain.ts&view=editor) -[Stackblitz Demo](https://stackblitz.com/edit/nodets-bnycf1?embed=1&file=src/main.ts&view=editor) +### Deposit -### Deposit (Coming soon) +- [Stackblitz Demo](https://stackblitz.com/edit/nodets-7cdu1z?embed=1&file=src%2Fmain.ts&view=editor) ### Withdraw (Coming soon) diff --git a/docs.renegade.fi/docs/technical-reference/useful-addresses.md b/docs.renegade.fi/docs/technical-reference/useful-addresses.md new file mode 100644 index 00000000..3b1068ae --- /dev/null +++ b/docs.renegade.fi/docs/technical-reference/useful-addresses.md @@ -0,0 +1,34 @@ +--- +sidebar_position: 1 +description: Getting started with the Renegade Typescript SDK. +--- + +# Useful Addresses + +## Contract Addresses + +| Contract | Arbitrum One Address | Arbitrum Sepolia Address | +|----------|------------------------|----------------------------| +| [Darkpool Proxy](https://github.com/renegade-fi/renegade-contracts/blob/main/contracts-stylus/src/contracts/darkpool.rs) | `0x30bd8eab29181f790d7e495786d4b96d7afdc518` | `0x9af58f1ff20ab22e819e40b57ffd784d115a9ef5` | +| [Permit2](https://github.com/Uniswap/permit2) | `0x000000000022D473030F116dDEE9F6B43aC78BA3` | `0x9458198bcc289c42e460cb8ca143e5854f734442` | + +## Relayer and Price Reporter Addresses + +| Name | Arbitrum One Address | Arbitrum Sepolia Address | +|----------|------------------------|----------------------------| +| [Renegade](https://github.com/renegade-fi/renegade) | `mainnet.cluster0.renegade.fi` | `testnet.cluster0.renegade.fi` | +| [Price Reporter](https://github.com/renegade-fi/renegade/tree/main/workers/price-reporter) | `mainnet.price-reporter.renegade.fi` | `testnet.price-reporter.renegade.fi` | + +## Whitelisted Tokens + +| Arbitrum One Token Mapping | Arbitrum Sepolia Token Mapping | +|----------------------------|----------------------------| +| [View on Github](https://github.com/renegade-fi/token-mappings/blob/main/mainnet.json) | [View on Github](https://github.com/renegade-fi/token-mappings/blob/main/testnet.json) | + +:::note +In the early days of the protocol, certain tokens are whitelisted. +::: + +## Arbitrum public RPC endpoints + +Refer to the [Arbitrum Docs](https://docs.arbitrum.io/build-decentralized-apps/reference/node-providers) for information such as RPC endpoints, chain IDs, and block explorers. \ No newline at end of file diff --git a/docs.renegade.fi/docs/typescript-sdk/_category_.json b/docs.renegade.fi/docs/typescript-sdk/_category_.json deleted file mode 100644 index a578272f..00000000 --- a/docs.renegade.fi/docs/typescript-sdk/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Typescript SDK", - "position": 4 -} diff --git a/docs.renegade.fi/sidebars.js b/docs.renegade.fi/sidebars.js index 55241c51..a62657fb 100644 --- a/docs.renegade.fi/sidebars.js +++ b/docs.renegade.fi/sidebars.js @@ -52,10 +52,11 @@ const sidebars = { }, { type: "category", - label: "API Docs", + label: "Technical Reference", collapsed: false, items: [ - "typescript-sdk/getting-started", + "technical-reference/useful-addresses", + "technical-reference/typescript-sdk", ], }, ],