From a2351851873d48400a3523da3c34f61030caff1b Mon Sep 17 00:00:00 2001 From: haochizzle <36713098+haochizzle@users.noreply.github.com> Date: Wed, 2 Oct 2024 04:53:58 -0400 Subject: [PATCH] chore: sprinter react docs + updates (#60) - [x] add sprinter-react docs - [x] update sprinter-sdk class reference docs - [x] update API documentation --- .../01-introduction/04-supported-networks.md | 4 +- docs/docs/03-sdk/03-class-reference.md | 74 ++++++++++-- docs/docs/03-sdk/05-react.md | 86 ++++++++++++++ docs/docs/04-api/05-solutions.md | 107 ++++++++++++++++++ 4 files changed, 260 insertions(+), 11 deletions(-) create mode 100644 docs/docs/03-sdk/05-react.md diff --git a/docs/docs/01-introduction/04-supported-networks.md b/docs/docs/01-introduction/04-supported-networks.md index 8778d12..821d0fc 100644 --- a/docs/docs/01-introduction/04-supported-networks.md +++ b/docs/docs/01-introduction/04-supported-networks.md @@ -22,6 +22,6 @@ New routes, networks, and tokens can readily be added by the Sprinter team. Plea Hover over network icon or token to show available routes ::: -| Mainet | Testnet | -|-------------------------|------------| +| Mainnet | Testnet | +|--------------------------|------------| | | | diff --git a/docs/docs/03-sdk/03-class-reference.md b/docs/docs/03-sdk/03-class-reference.md index b166712..2e2a2e4 100644 --- a/docs/docs/03-sdk/03-class-reference.md +++ b/docs/docs/03-sdk/03-class-reference.md @@ -6,15 +6,20 @@ sidebar_position: 3 This section details the methods available to the `Sprinter` class in the Sprinter SDK. Use this reference to understand how to utilize the `Sprinter` class in your decentralized applications (dApps). +:::tip +`FetchOptions` is an object that contains settings for configuring how the fetch requests are made by the SDK. There are two parameters that can be adjusted including `signal`, which hides the request, and `baseURL`, which sets the target for either mainnet or testnet. +`AggregateBalances` represents the user's token balances across multiple blockchains. It maps a token symbol to the balance information, which includes the total balance and an array of token balances for each chain. +::: + ## Methods ### `constructor(fetchOptions: Omit)` -Initializes the SDK with the given Ethereum provider. +Initializes the SDK with the given fetch options. The `signal` property is explicitly excluded, and only `baseURL` can be set. #### Parameters -- `fetchOptions`: TODO :Sad: +- `fetchOptions: Omit`: An object that allows specifying additional fetch options, excluding the `signal` property. #### Example @@ -54,7 +59,7 @@ sprinter.getAvailableChains().then(chains => { }); ``` -### `getUserBalances(account: Address, tokens?: FungibleToken[]): Promise<{ [symbol: TokenSymbol]: { balances: FungibleTokenBalance[]; total: string } }>` +### `getUserBalances(account: Address, tokens?: FungibleToken[], options?: FetchOptions): Promise` Fetches the user's balances for specified tokens across multiple blockchains. If no tokens are specified, it fetches balances for all available tokens. @@ -68,10 +73,11 @@ Method will always return native tokens under `ETH` key - `account`: Targeted account address. - `tokens`: An optional array of fungible token objects. +- `options?: FetchOptions`: Optional fetch options to configure how the request is made. #### Returns -- `Promise<{ [symbol: TokenSymbol]: { balances: FungibleTokenBalance[]; total: string } }>`: A promise that resolves to an object mapping token symbols to balance information. +- `Promise`: A promise that resolves to an object mapping token symbols to balance information. The balance information contains the total balance and an array of token balances on different chains. #### Example @@ -82,9 +88,12 @@ sprinter.getUserBalances(ownerAddress).then(balances => { }); ``` -### `getSolution(settings: SolutionOptions): Promise` +### `getSolution(settings: SolutionOptions | ContractSolutionOptions, options?: FetchOptions): Promise` -Retrieves the optimal solution for managing cross-chain transactions based on the provided settings. +There are two variations of this method. One is used for general cross-chain transactions, and another handles contract call solutions: +- `SolutionOptions`: For standard cross-chain transfers. +- `ContractSolutionOptions`: For contract call solutions. +You can specify options to control how the request is made. #### Parameters @@ -103,15 +112,62 @@ Retrieves the optimal solution for managing cross-chain transactions based on th #### Example ```typescript -const ownerAddress = "0x3E101Ec02e7A48D16DADE204C96bFF842E7E2519"; -sprinter.getSolution({ +const solutionSettings = { account: ownerAddress, token: "USDC", destinationChain: 42161, // Destination chain ID amount: 1000000000 // Amount in the smallest unit (e.g., wei) -}).then(solution => { +}; + +sprinter.getSolution(solutionSettings).then(solution => { console.log('Transaction solution:', solution); }); + +// For contract call solution +const settings = { + account: "0x3e101ec02e7a48d16dade204c96bff842e7e2519", + destinationChain: 11155111, + token: "USDC", + amount: "100000000", + contractCall: { + callData: "0xabcdef", // encoded contract call data + contractAddress: "0x1234567890abcdef", + gasLimit: 21000, + recipient: "0xRecipientAddress" // for native contract call (usually is contract that will receive tokens) + }, + +sprinter.getSolution(contractSolutionSettings).then(contractSolution => { + console.log('Contract call solution:', contractSolution); +}); +``` + +### `getCallSolution(settings: ContractSolutionOptions, options?: FetchOptions): Promise` + +Retrieves a solution for executing a contract call across chains. + +#### Parameters + +- `settings: ContractSolutionOptions`: The options required for creating a cross-chain contract call solution. +- `options: FetchOptions`: Optional fetch options to configure how the request is made. + +#### Returns + +- `Promise`: A promise that resolves to a solution response object containing details about the contract call execution. + +#### Example + +```ts +const contractCallSettings = { + account: ownerAddress, + contractCall: true, + token: "USDC", + destinationChain: 42161, // Destination chain ID + amount: 1000000000 // Amount in the smallest unit (e.g., wei) +}; + +sprinter.getCallSolution(contractCallSettings).then(callSolution => { + console.log('Contract call solution:', callSolution); +}); ``` ## Data Types diff --git a/docs/docs/03-sdk/05-react.md b/docs/docs/03-sdk/05-react.md new file mode 100644 index 0000000..c99a881 --- /dev/null +++ b/docs/docs/03-sdk/05-react.md @@ -0,0 +1,86 @@ +--- +sidebar_position: 5 +--- + +# Sprinter React SDK + +The Sprinter React SDK is a React wrapper for the [Sprinter SDK](01-overview.md), enabling easy interaction with blockchain networks through React components and hooks. It provides context management and custom hooks for retrieving balances, tokens, supported chains, and solutions for asset transfers. + +## Installation + +To install the package, use npm or yarn: + +```bash +npm install @chainsafe/sprinter-react +``` +or +```bash +yarn add @chainsafe/sprinter-react +``` + +## Usage + +Wrap your application in the `SprinterContext` to gain access to blockchain-related data within your component tree. + +### Example + +```ts +import React from 'react'; +import { SprinterContext } from '@chainsafe/sprinter-react'; + +const App = () => ( + + + +); + +export default App; +``` +Inside your components, you can use the provided hooks to interact with blockchain data: + +```ts +import React, { useEffect } from 'react'; +import { useSprinterBalances, useSprinterTokens } from '@chainsafe/sprinter-react'; + +const YourComponent = () => { + const ownerAddress = "0xYourAddressHere"; + const { balances, getUserBalances } = useSprinterBalances(ownerAddress); + + useEffect(() => { + getUserBalances(); + }, [getUserBalances]); + + return ( +
+

Balances:

+ 
{JSON.stringify(balances, null, 2)}
+

Available Tokens:

+ 
{JSON.stringify(tokens, null, 2)}
+
+ ); +}; + +export default YourComponent; +``` + +### Available Hooks + +The following hooks are provided by the SDK: + +- `useSprinter()`: Access everything from the Sprinter context. +- `useSprinterBalances(account: Address)`: Retrieve user balances for a given account. +- `useSprinterTokens()`: Retrieve available tokens. +- `useSprinterChains()`: Retrieve available blockchain chains. +- `useSprinterSolution()`: Retrieve solutions for asset transfers. +- `useSprinterCallSolution()`: Call solutions for transferring assets. + +### Custom Fetch Options + +You can pass custom fetch options when initializing the context: + +```ts + + + +``` + diff --git a/docs/docs/04-api/05-solutions.md b/docs/docs/04-api/05-solutions.md index f532981..88bb245 100644 --- a/docs/docs/04-api/05-solutions.md +++ b/docs/docs/04-api/05-solutions.md @@ -6,6 +6,113 @@ sidebar_position: 5 This section explains how to get solutions for specific actions using the Sprinter API. +## POST - /solution/call + +### Description + +This endpoint calculates the best single-hop solution along with a contract call. + +### Endpoint + +`POST /solution/call` + +### Request Body + +The request body should be a JSON object containing the following fields: + +- `account`: The account address initiating the transaction. +- `amount`: The amount to be transferred. +- `destinationChain`: The ID of the destination blockchain. +- `destinationContractCall`: Represents the contract call that will be executed on the destination chain. + - `approvalAddress`: The address to which the token approval is granted, allowing the contract to spend a certain amount of tokens on behalf of the user. + - `callData`: The ABI-encoded function call data to be executed on the destination contract. + - `contractAddress`: The address of the contract on the destination chain that will receive the call. + - `gasLimit`: The maximum gas limit for the contract call. + - `outputTokenAddress`: The address of the token on the destination chain where the output of the contract call is returned. +- `recipient`: The address that will receive the final output of the transaction on the destination chain. +- `threshold?`: An optional threshold parameter that sets limits or conditions +- `token`: The token symbol (e.g., "USDC"). +- `type`: The type of transaction being executed (e.g., cross-chain transfer, contract interaction, etc.). +- `whitelistedSourceChains?`: An optional array of whitelisted source chain IDs. + +### Example Request + +```shell +curl -X 'POST' \ + 'https://api.sprinter.buildwithsygma.com/solution/call' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "account": "string", + "amount": "string", + "destination": 1, + "destinationContractCall": { + "approvalAddress": "string", + "callData": "string", + "contractAddress": "string", + "gasLimit": 0, + "outputTokenAddress": "string" + }, + "recipient": "string", + "threshold": "string", + "token": "string", + "type": "fungible", + "whitelistedSourceChains": [ + 1 + ] +}' +``` + +### Example Response + +```json +{ + "data": [ + { + "amount": "", + "approvals": [ + { + "chainId": 1, + "data": "string", + "from": "string", + "gasLimit": "string", + "gasPrice": "string", + "to": "string", + "value": "string" + } + ], + "destinationChain": 1, + "destinationTokenAddress": "string", + "duration": 0, + "fee": { + "amount": "", + "amountUSD": 0 + }, + "gasCost": { + "amount": "", + "amountUSD": 0 + }, + "senderAddress": "string", + "sourceChain": 1, + "sourceTokenAddress": "string", + "tool": { + "logoURI": "string", + "name": "string" + }, + "transaction": { + "chainId": 1, + "data": "string", + "from": "string", + "gasLimit": "string", + "gasPrice": "string", + "to": "string", + "value": "string" + } + } + ] +} +``` + ## GET - /solutions/aggregation ### Description