chore: sprinter react docs + updates (#60)

- [x] add sprinter-react docs - [x] update sprinter-sdk class reference docs - [x] update API documentation
ChainSafe · Oct 2, 2024 · a235185 · a235185
1 parent 9ba9ab8
commit a235185
Show file tree

Hide file tree

Showing 4 changed files with 260 additions and 11 deletions.
diff --git 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    |
+|--------------------------|------------|
 | <SankeyNetworkToken url="https://api.sprinter.buildwithsygma.com/" /> | <SankeyNetworkToken url="https://api.test.sprinter.buildwithsygma.com/" /> |
diff --git 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<FetchOptions, "signal">)`
 
-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<FetchOptions, "signal">`: 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<AggregateBalances>`
 
 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<AggregateBalances>`: 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<SolutionResponse>`
+### `getSolution(settings: SolutionOptions | ContractSolutionOptions, options?: FetchOptions): Promise<SolutionResponse>`
 
-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<SolutionResponse>`
+
+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<SolutionResponse>`: 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
@@ -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 = () => (
+  <SprinterContext>
+    <YourComponent />
+  </SprinterContext>
+);
+
+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 (
+    <div>
+      <h1>Balances:</h1>
+      <pre>{JSON.stringify(balances, null, 2)}</pre>
+      <h1>Available Tokens:</h1>
+      <pre>{JSON.stringify(tokens, null, 2)}</pre>
+    </div>
+  );
+};
+
+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
+<SprinterContext fetchOptions={{ baseUrl: "https://api.test.sprinter.buildwithsygma.com/" }}>
+  <YourComponent />
+</SprinterContext>
+```
+
diff --git 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