# Earn Kit

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> **Note:** Earn Kit is coming soon. The APIs documented here are published for
> early integration and feedback; vault availability and production readiness
> will be announced ahead of general availability.

Earn Kit is a Circle SDK for DeFi lending vault earn flows. It provides typed
operations for discovering vaults, fetching wallet positions, previewing
deposits, withdrawals, and reward claims, and executing deposit, withdraw, and
claim rewards transactions.

## Installation

```bash
npm install @circle-fin/earn-kit
# or
yarn add @circle-fin/earn-kit
```

Install an adapter for the wallet stack you use. For EVM flows:

```bash
npm install @circle-fin/adapter-viem-v2 viem
# or
yarn add @circle-fin/adapter-viem-v2 viem
```

## Quick Start

```typescript
import { Blockchain, EarnChain, EarnKit } from '@circle-fin/earn-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new EarnKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY,
})

const quote = await kit.getDepositQuote({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Expected shares: ${quote.expectedShares.amount}`)

const depositResult = await kit.deposit({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Deposit submitted: ${depositResult.txHash}`)
```

## Deposits

Same-chain deposits keep the existing approval and Earn action flow. Cross-chain
deposits are selected only when `to` is present and `to.chain` differs from
`from.chain`.

```typescript
const bridgeDeposit = await kit.deposit({
  from: { adapter, chain: Blockchain.Ethereum_Sepolia },
  to: {
    chain: EarnChain.Arc_Testnet,
    recipientAddress: '0x1234567890123456789012345678901234567890',
  },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Bridge deposit submitted: ${bridgeDeposit.execId}`)
```

For cross-chain deposits, `to.recipientAddress` is the destination wallet that
receives the vault position and `from.address` can be used as an optional
source wallet override. The returned result contains the bridge execution ID,
submit status, source chain, destination chain, vault address, amount, and
prepared bundle expiry timestamp. The SDK generates the bridge execution ID
and `retry()` resumes the same bridge execution after a failure.

Cross-chain Earn deposits currently support Ethereum Sepolia, Arbitrum Sepolia,
and Base Sepolia as source chains, with Arc Testnet as the Earn destination
chain.

## Discovering Vaults

Iterate every vault available on a chain without managing pagination:

```typescript
for await (const vault of kit.exploreVaultsIterator({
  chain: 'Arc_Testnet',
  sortBy: 'apy',
})) {
  console.log(`${vault.name}: ${(vault.currentApy * 100).toFixed(2)}% APY`)
}
```

For paged UIs that need totals, fetch one page at a time instead:

```typescript
const { vaults, pagination } = await kit.exploreVaults({
  chain: 'Arc_Testnet',
  page: 1,
})
console.log(`Page 1 of ${pagination.totalPages} (${pagination.totalCount} vaults)`)
```

## Supported Chains

Use `kit.getSupportedChains()` or the functional `getSupportedChains(context)`
helper to read the supported chain definitions from configured earn providers.

## Core Operations

- `getVaults`: fetch vault metadata for one or more vaults.
- `exploreVaultsIterator`: lazily iterate every vault available on a chain
  with optional protocol, asset, APY, and TVL filters. Pages are fetched on
  demand, so there is no page arithmetic to manage.
- `exploreVaults`: fetch a single page of vault discovery results with
  pagination metadata, for paged UIs.
- `getPosition`: fetch a wallet position for a vault.
- `getDepositQuote`: preview a deposit.
- `getWithdrawalQuote`: preview a withdrawal.
- `getClaimRewardsQuote`: preview claimable rewards.
- `deposit`: execute a deposit transaction.
- `withdraw`: execute a withdrawal transaction.
- `claimRewards`: claim rewards, or return without a transaction when none are
  claimable.
- `getCrossChainDepositStatus`: read the current bridge status of a cross-chain
  deposit by `execId`.
- `waitForCrossChainDeposit`: poll a cross-chain deposit until it reaches a
  terminal bridge state (or the wait budget elapses).

## Configuration

Earn Kit works without a Kit Key. A Kit Key can be passed per operation for
permissioned access and attribution:

```typescript
await kit.getVaults({
  vaults: [
    {
      chain: 'Arc_Testnet',
      vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
    },
  ],
  config: {
    kitKey: process.env.KIT_KEY,
  },
})
```

## License

This project is licensed under the Apache 2.0 License. Contact [support](https://help.circle.com/s/submit-ticket) for details.