@aryze/reforge-sdk/README.md

SDK for interacting with reForge from ARYZE.

# reForge SDK

This SDK simplifies the process of [reForge](https://docs.aryze.io/en/products-and-services/reforge) - preparing and executing cross-chain transactions for Ethereum-compatible tokens. It leverages `ethers.js` for blockchain interactions, providing utilities to prepare transaction data and execute transactions across supported chains.

## Features

- Prepare transaction data for cross-chain transfers.
- Execute transactions on Ethereum-compatible blockchains.
- Supports multiple chains and tokens out of the box.
- Easy integration with existing Ethereum projects.

## Installation

To use this SDK in your project, you first need to install ethers.js. You can install both ethers.js and this SDK via npm:

```bash
npm install @aryze/reforge-sdk
```

## Quick Start

Here's how to quickly get started with the SDK:

### 1. Import the SDK into your project:

```javascript
// Importing required functions and constants from the ARYZE Reforge SDK and ethers.js library.
// Import necessary functions and constants from the ARYZE Reforge SDK.
import { SUPPORTED_TEST_CHAINS, TOKEN_IDS, executeReforge, prepareReforge } from '@aryze/reforge-sdk';
```

### 2. Preparing a Transaction.

Prepare your transaction data for a cross-chain transfer:

```javascript
// Define the token symbol to transfer.
const symbol = 'eEUR'; // Options: eEUR, eGBP, eUSD, eSGD

// Source blockchain information: Here we're using Binance Testnet.
const sourceChainId = SUPPORTED_TEST_CHAINS.BINANCE_TESTNET;
const sourceToken = TOKEN_IDS[sourceChainId][symbol]; // The token's contract address on the source chain.

// Destination blockchain information: Here we're targeting the Mumbai testnet.
const destinationChainId = SUPPORTED_TEST_CHAINS.MUMBAI;
const destinationToken = TOKEN_IDS[destinationChainId][symbol]; // The token's contract address on the destination chain.

// Alternative simpler method to get the token address, if available.
// const destinationToken = TOKEN_NAMES.MUMBAI.eEUR;

// Prepare the transaction for reforge. This includes specifying the amount,
// source and destination token addresses, and the destination chain ID.
// Note: ARYZE ERC20 tokens are assumed to have 18 decimals.
const tx = prepareReforge(
  '100', // Amount of tokens to transfer, specified in the smallest unit (e.g., wei for ETH).
  sourceToken,
  destinationToken,
  destinationChainId
);
```

### 3. Executing a Transaction.

Execute the prepared transaction using wallet credentials:

```javascript
// Wallet information needed for executing the transaction.
// WARNING: Hardcoding private keys is unsafe. This key is for demonstration and should be securely managed.
const walletData = {
  rpcUrl: 'https://bsc-testnet.publicnode.com', // RPC URL for the source blockchain network.
  privateKey: 'YOUR_WALLET_PRIVATE_KEY' // The sender's private key.
};

// Execute the prepared transaction using the provided wallet data.
// This function sends the actual transaction to the blockchain and returns a receipt.
const request = { tx: responce.tx, walletData };
const receipt = await executeReforgeAsync(request);

// Log the transaction receipt to the console for verification.
console.log(receipt);
```

# API Reference

This section provides detailed information about the SDK's functions and their parameters.

### `prepareReforge(sourceAmount, sourceToken, destinationToken, destinationChainId, sourceRpcUrl)`

Prepares the transaction data for a cross-chain transfer.

### Parameters

- **`sourceAmount`**: `string` - The amount of tokens to transfer, specified in ethers.
- **`sourceToken`**: `string` - The contract address of the token on the source chain.
- **`destinationToken`**: `string` - The contract address of the token on the destination chain.
- **`destinationChainId`**: `number | string"` - The chain ID of the destination blockchain.
- **`sourceRpcUrl`**: `string` (optional) - The RPC URL of the source blockchain.

### Returns

- **`Object`**: An object containing the status of the operation (true if successful, false otherwise) and the transaction data or error message.

### `executeReforgeAsync(request)`

Executes a transaction asynchronously, intended for sending a prepared transaction.

### Parameters

- **`request`**: `TXRequest` - An object containing the transaction data and wallet information.

### Returns

- **`Promise<object>`**: A promise that resolves to an object containing the status of the transaction (true if successful, false otherwise), and either the transaction receipt or error message.

### `executeReforge(request)`

Executes a transaction, similar to executeReforgeAsync but may be used in contexts where the asynchronous pattern is preferred.

### Parameters

- **`request`**: `TXRequest` - An object containing the transaction data and wallet information.

### Returns

- **`Promise<object>`**: A promise that resolves to an object with the transaction's status and details.

## Types and Interfaces

### TXRequest

An interface for transaction request data.

#### Properties:

- **`tx`** : `string` - The encoded transaction data.
- **`walletData`** : `IWalletData` - Information about the wallet executing the transaction.

### IWalletData

An interface for wallet data required to execute a transaction.

#### Properties:

- **`rpcUrl`** : `string` - The RPC URL of the blockchain network.
- **`privateKey`** : `string` - The private key of the wallet.
- **`signer`** : `JsonRpcSigner` - The object of signer (eg. ether js `JsonRpcSigner`)

## Supported Chains and Tokens

[Details on supported chains and tokens](https://docs.aryze.io/en/products-and-services/aryze-digital-cash)

## Constants

- **`SUPPORTED_CHAINS`**: Object mapping supported chain names to their chain IDs.
- **`TOKEN_IDS`**: Object mapping chain IDs to token contract addresses.
- **`TOKEN_NAMES`**: Object mapping token names to token contract addresses.