FullReserve SDK

TypeScript SDK for interacting with the FullReserve Protocol smart contracts.

• Minimal Factory Classes: Custom factory classes provide only the connect() functionality needed for contract interaction
• Type Safety: Full TypeScript support with generated types from contract ABIs

Features

• Direct typed access to all FullReserve smart contracts
• High-level methods for common operations
• Mint operation with automatic oracle data handling
• Mint simulation for calculating wrapper token amounts
• Unmint simulation for calculating underlying asset amounts
• RedStone oracle integration for yield asset pricing
• Comprehensive error handling and validation
• TypeScript support with full type safety

Installation

npm install @alignmintdev/fullreserve-sdk

Usage

Basic Setup

import { ethers } from "ethers";
import { FullReserveSDK } from "@alignmintdev/fullreserve-sdk";

// Connect to a provider
const provider = new ethers.JsonRpcProvider("https://your-rpc-url");
// Or use a signer for write operations
const signer = new ethers.Wallet("your-private-key", provider);

// Initialize SDK
const sdk = new FullReserveSDK(chainId, signer);

Working with Contracts

The SDK provides typed access to all FullReserve contracts:

// Connect to a WrapperToken
const operations = sdk.contracts.WrapperTokenOperations(
  "0x...operationsAddress"
);

// Read information
console.log(await operations.isUnmintAvailable());

Working with methods

The SDK provides high-level methods to interact with the contracts:

Mint Simulation

// Simulate minting operation
const mintSimulation = sdk.methods.simulateMintOperation({
  amount: "1000000000", // Amount in yield asset
  yieldAsset: yieldAssetInfo, // Yield asset from API
  wrapperToken: wrapperTokenInfo, // Wrapper token from API
  yieldAssetConfig: yieldAssetConfig, // Yield asset configuration from API from FullReserve yieldAssets field
  minAmountOut: "990000000000000000000", // Optional slippage protection
});

console.log("Wrapper tokens to receive:", mintSimulation.wrapperTokenAmount);

Unmint Simulation

// Simulate unminting operation
const unmintSimulation = sdk.methods.simulateUnmintOperation({
  amount: "1000000000000000000000", // Amount in wrapper token decimals (18)
  wrapperToken: wrapperTokenInfo, // Wrapper token from API
  underlyingAsset: underlyingAssetInfo, // Underlying asset for wrapper token from API
  yieldAssetConfig: yieldAssetConfig, // Yield asset configuration from API from FullReserve yieldAssets field
  minAmountOut: "990000000", // Optional slippage protection
});

console.log(
  "Underlying asset to receive:",
  unmintSimulation.underlyingAssetAmount
);
console.log("Unmint fee:", unmintSimulation.unmintFee);

Example: Minting Wrapped Tokens using high level methods

// Mint wrapped tokens using high-level method
const mintParams = {
  operationsContractAddress: "0x...operationsAddress", // Address of the operations contract of this context FullReserve
  amount: "1000000000", // Amount in yield asset decimals
  wrapperToken: wrapperTokenInfo, // Wrapper token from API (includes price)
  underlyingAsset: underlyingAssetInfo, // Underlying asset for wrapper token price calculation
  yieldAsset: yieldAssetInfo, // Yield asset from API (includes price, decimals)
  yieldAssetConfig: yieldAssetConfig,
  lstUnderlyingAsset: lstUnderlyingAssetInfo, // Optional: LST underlying asset of yieldAsset for LST price calculation
  minAmountOut: "990000000000000000000", // Optional: minimum wrapper tokens expected
};

const gasEstimate = await sdk.methods.mintOperationEstimateGas(mintParams);
console.log(`Estimated gas: ${gasEstimate.toString()}`);

await sdk.methods.mintOperation(mintParams);

Example: Multi-Mint with Multiple Assets

// Mint wrapped tokens with multiple assets in one transaction
const multiMintParams = {
  operationsContractAddress: "0x...operationsAddress",
  wrapperToken: wrapperTokenInfo,
  underlyingAsset: underlyingAssetInfo,
  mints: [
    {
      amount: "1000000000", // 1000 USDC (6 decimals)
      yieldAsset: usdcInfo,
      minAmountOut: "990000000000000000000", // 990 wrapped tokens
    },
    {
      amount: "500000000000000000000", // 500 DAI (18 decimals)
      yieldAsset: daiInfo,
      minAmountOut: "495000000000000000000", // 495 wrapped tokens
    },
  ],
  lstUnderlyingAssets: new Map([
    [stETHAddress, ethInfo], // Optional: LST mappings
  ]),
};

const multiMintGasEstimate = await sdk.methods.multiMintOperationEstimateGas(multiMintParams);
console.log(`Estimated gas (multi-mint): ${multiMintGasEstimate.toString()}`);

await sdk.methods.multiMintOperation(multiMintParams);

Example: Unminting Wrapped Tokens using high level methods

// Unmint wrapped tokens using high-level method
const unmintParams = {
  operationsContractAddress: "0x...operationsAddress", // Address of the operations contract of this context FullReserve
  amount: "1000000000000000000000", // Amount in wrapper token decimals (18)
  minAmountOut: "990000000000000000000", // Optional: minimum underlying asset expected
};

const unmintGasEstimate = await sdk.methods.unmintOperationEstimateGas(unmintParams);
console.log(`Estimated gas (unmint): ${unmintGasEstimate.toString()}`);

await sdk.methods.unmintOperation(unmintParams);

Example: Minting Wrapped Tokens using direct contract calls

// Connect to operations contract
const operations = sdk.contracts.WrapperTokenOperations(
  "0x...operationsAddress"
);

// Approve yield asset spending first
const yieldAsset = new ethers.Contract(yieldAssetAddress, ERC20_ABI, signer);
await yieldAsset.approve(operations.address, amount);

// Mint wrapped tokens
const tx = await operations.mintWrapperToken(
  yieldAssetAddress,
  amount,
  minWrapperTokens,
  "0x"
);

await tx.wait();

Building the SDK

The SDK uses a multi-step build process to generate types from contract ABIs:

# Install dependencies
npm install

# Build the SDK (copies ABIs, generates types, compiles TypeScript)
npm run build

# Or run individual steps:
npm run copy-abis      # Copy ABIs from contracts
npm run generate-types # Generate TypeScript types
npm run build      # Run all build steps

Updating Types

When smart contracts are updated:

1. Ensure the contracts are compiled in the FullReserveContracts_EVM directory
2. Run npm run build in the SDK directory to regenerate types
3. The build process will:
   • Copy the latest ABIs from the contracts
   • Generate TypeScript interfaces (without bytecode)
   • Create minimal factory classes for contract connections

Development

Publishing

npm version patch

npm publish --dry-run

npm publish --access public

Building

npm run build

Cleaning

npm run clean  # Removes dist/, generated types, and ABIs

## Testing

The SDK includes comprehensive unit tests with >97% code coverage.

### Running Tests

```bash
# Run all tests
npm test

# Run tests with coverage report
npm test -- --coverage

# Run specific test file
npm test -- tests/FullReserveSDK.test.ts

# Run tests in watch mode
npm test -- --watch

Test Structure

tests/
├── FullReserveSDK.test.ts           # Main SDK class tests
├── methods/
│   ├── mintOperation.test.ts      # Mint operation tests
│   ├── unmintOperation.test.ts    # Unmint operation tests
│   ├── simulateMintOperation.test.ts
│   └── simulateUnmintOperation.test.ts
├── utils/
│   ├── mintCalculations.test.ts   # Mint utility tests
│   └── unmintCalculations.test.ts # Unmint utility tests
└── fixtures/
    └── mockContracts.ts           # Mock infrastructure

Mock Infrastructure

The test suite includes comprehensive mocks for:

• Ethers providers and signers
• Contract interactions and transactions
• RedStone oracle data
• Error scenarios

Requirements

• Node.js >= 18.0.0
• ethers.js v6