JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 29
  • Score
    100M100P100Q70995F
  • License MIT

Concrete SDK for interacting with vault contracts

Package Exports

  • @concrete-xyz/sdk
  • @concrete-xyz/sdk/react
  • @concrete-xyz/sdk/wagmi

Readme

@concrete-xyz/sdk

SDK for interacting with vault contracts on multiple EVM networks.

⚠️ Beta Warning: This package is currently in closed beta. If you encounter any issues, please contact us for support.

Installation

Core SDK

npm install @concrete-xyz/sdk

React Integration

npm install @concrete-xyz/sdk
# Then import from the react subpath
import { useVault } from "@concrete-xyz/sdk/react";

Wagmi Integration

npm install @concrete-xyz/sdk
# Then import from the wagmi subpath
import { useVault, useVaultQuery } from "@concrete-xyz/sdk/wagmi";

Quick Start

1. Core SDK (Vanilla JavaScript/TypeScript)

For direct usage without React or Wagmi:

import { getVault } from "@concrete-xyz/sdk";
import { ethers } from "ethers";

// Create provider
const provider = new ethers.JsonRpcProvider("YOUR_RPC_URL");

// Create vault instance
const vault = getVault(
  "0x15cE9bE6609db102b70D68ca75a39c555bEa5Fac", // vault address
  "Ethereum", // network name
  provider, // ContractRunner instance
);

// Get vault details
const vaultDetails = await vault.getVaultDetails();
console.log("Vault Symbol:", vaultDetails.symbolDetails);

React Integration

For React applications, the SDK provides a custom hook useVault that integrates seamlessly with your existing providers.

Key Features:

  • Requires explicit provider and signer instances (both are mandatory)
  • Full control over network configuration
  • Integrates with any React state management solution

React: useVault(address, network, provider, signer)

The React hook for interacting with vault contracts. Requires explicit provider and signer instances.

Parameters:

  • address (string): The vault contract address
  • network (EnabledNetwork): The blockchain network name
  • provider (ContractRunner): Provider for read operations
  • signer (JsonRpcSigner): Signer for write operations

Returns: Vault instance with all available methods

Usage Example:

import { useVault } from "@concrete-xyz/sdk/react";
import { useCore } from "~/core"; // Your core provider

export default function VaultComponent() {
  const { web3 } = useCore();
  const provider = web3.networkProvider;
  const signer = web3.clientProvider;

  const vault = useVault(
    "0x585934AfBf1FA9f563b80283F8B916Dd8F66a9b6", // vault address
    "Berachain", // network name
    provider, // ContractRunner instance
    signer // Signer for write operations
  );

  // Use vault methods
  const vaultDetails = await vault.getVaultDetails();

  return <div>Vault: {String(vault)}</div>;
}

Wagmi Integration

For applications using Wagmi, the SDK provides a simplified hook that automatically uses Wagmi's context.

Key Features:

  • Automatic provider and signer detection
  • Seamless integration with Wagmi's ecosystem
  • Minimal configuration required
  • Built-in React Query integration with useVaultQuery
  • Automatic caching and state management

Wagmi: useVault(address, network)

The Wagmi hook for interacting with vault contracts. Automatically uses Wagmi's configured providers and signers.

Parameters:

  • address (string): The vault contract address
  • network (EnabledNetwork): The blockchain network name

Returns: Vault instance with all available methods

Usage Example:

import { useVault } from "@concrete-xyz/sdk/wagmi";

export default function VaultComponent() {
  const vault = useVault(
    "0x585934AfBf1FA9f563b80283F8B916Dd8F66a9b6", // vault address
    "Berachain" // network name
  );

  // Use vault methods
  const vaultDetails = await vault.getVaultDetails();

  return <div>Vault: {String(vault)}</div>;
}

Wagmi: useVaultQuery(options)

The Wagmi hook for querying vault data with automatic caching and state management. Built on top of React Query for optimal performance.

Parameters:

  • options (object):
    • address (string): The vault contract address
    • network (EnabledNetwork): The blockchain network name
    • queryKey (array): Unique key for React Query caching
    • queryFn (function): Function that receives the vault instance and returns the data to query

Returns: React Query result object with data, isLoading, error, etc.

Usage Example:

import { useVault, useVaultQuery } from "@concrete-xyz/sdk/wagmi";

export default function VaultComponent() {
  const vaultQuery = useVaultQuery({
    address: testAddress,
    network: testNetwork,
    queryKey: ["vaultInfo"],
    queryFn: async (vault) => await vault.getVaultDetails(),
  });

  return (
    <div>
      <pre>
        {JSON.stringify(vaultQuery.data, null, 2)}
      </pre>
    </div>
  );
}

Hook Comparison

Key Differences:

  • React version: Requires explicit provider and signer instances
  • Wagmi version: Automatically uses Wagmi's configured providers and signers
  • Wagmi version: Includes additional useVaultQuery hook for React Query integration
  • Both versions: Return the same vault instance with identical methods

Vanilla Examples

1. Get Vault Data

import { getVault } from "@concrete-xyz/sdk";
import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("YOUR_RPC_URL");
const vault = getVault("0x15cE9bE6609db102b70D68ca75a39c555bEa5Fac", "Ethereum", provider);

// Get complete vault information
const vaultDetails = await vault.getVaultDetails();
console.log("Vault Symbol:", vaultDetails.vaultAsset.symbol);
console.log("Underlying Asset:", vaultDetails.underlying.symbol);

2. Preview Deposit

// Preview conversion before depositing
const depositAmount = BigInt(1 * 10 ** Number(await vault.getUnderlyingDecimals())); // 18 decimals token
const preview = await vault.previewConversion(depositAmount);

console.log(`Input: ${depositAmount} ${vaultDetails.underlying.symbol}`);
console.log(`Output: ${preview.vaultTokensReciving} ${vaultDetails.vaultAsset.symbol}`);

3. Execute Deposit

// You need a signer for write operations
const signer = new ethers.Wallet("YOUR_PRIVATE_KEY", provider);
const vaultWithSigner = getVault("0x15cE9bE6609db102b70D68ca75a39c555bEa5Fac", "Ethereum", provider, signer);

// Approve tokens first
const approveTx = await vaultWithSigner.approve(vaultWithSigner.getAddress(), depositAmount);
await approveTx.wait();

// Execute deposit
const depositTx = await vaultWithSigner.deposit(depositAmount);
const receipt = await depositTx.wait();
console.log("Deposit successful:", receipt);

4. Execute Withdrawal

// Preview withdrawal
const withdrawAmount = BigInt(1 * 10 ** Number(await vault.decimals())); // 18 decimals underlying token + 9 decimal offset
const withdrawalPreview = await vault.previewConversion(withdrawAmount);

console.log(`Input: ${withdrawAmount} ${vaultDetails.vaultAsset.symbol}`);
console.log(`Output: ${withdrawalPreview.underlyingReciving} ${vaultDetails.underlying.symbol}`);

// Execute withdrawal (using the same signer from previous example)
const withdrawTx = await vaultWithSigner.redeem(withdrawAmount);
const receipt = await withdrawTx.wait();
console.log("Withdrawal successful:", receipt);

5. Get APY Details

import { getVault } from "@concrete-xyz/sdk";

const vault = getVault("0xE2d8267D285a7ae1eDf48498fF044241d04e9608", "Arbitrum");

// Get APY information
const apyDetails = await vault.getApyDetails();
console.log("APY Details:", apyDetails);

6. Get Oracle Price

import { getVault } from "@concrete-xyz/sdk";
import { ethers } from "ethers";

const rpcUrl = "https://arb1.arbitrum.io/rpc";
const provider = new ethers.JsonRpcProvider(rpcUrl);

const vault = getVault("0xE2d8267D285a7ae1eDf48498fF044241d04e9608", "Arbitrum", provider);

// Get underlying asset price from oracle
const underlyingPrice = await vault.getUnderlyingPrice();
console.log("Underlying Price:", underlyingPrice);

Supported Networks

The SDK supports multiple EVM networks including: Ethereum, Arbitrum, Corn, Morph, Berachain, and Katana.

Network Types:

  • Mainnet: Ethereum, Arbitrum
  • Testnet: Corn, Morph, Berachain, Katana

Note: Network support may vary based on your specific deployment. Always verify network compatibility before production use.

API Reference

getVault(address, network, clientProvider, signerProvider?)

Creates a new Vault instance for interacting with vault contracts.

Parameters:

  • address (string): The vault contract address
  • network (EnabledNetwork): The blockchain network name
  • clientProvider (ContractRunner): Provider for read operations
  • signerProvider (JsonRpcSigner, optional): Signer for write operations

Returns: Vault instance

Vault Methods

The vault is an abstraction of a ERC-4626 Tokenized Vault, which in turn is an ERC-20 token that represents shares of underlying assets.

Technically, all ERC-4626 vault methods are available, but the SDK provides a simplified interface focusing on the most commonly used operations. Some less frequently used methods may not be directly exposed through the SDK wrapper.

Commonly used methods (examples):

  • getVaultDetails(): Get complete vault information
  • previewConversion(amount): Preview deposit/withdrawal conversion
  • deposit(amount): Deposit underlying tokens for vault tokens
  • redeem(amount): Redeem vault tokens for underlying tokens
  • approve(spender, amount): Approve token spending
  • totalAssets(): Get total assets in vault
  • symbol(): Get vault symbol

Using ABI Directly

The SDK also provides access to both human-readable and raw ABI files for advanced use cases:

import abi from "@concrete-xyz/sdk/dist/src/core/contracts/abi/vault.json";
import rawAbi from "@concrete-xyz/sdk/dist/src/core/contracts/raw-abi/vault.json";

// Use vault human readable ABI
console.log(abi);

// Use vault raw ABI
console.log(rawAbi);

This allows you to create custom contract instances or integrate with other libraries while maintaining access to the standardized vault interfaces.