Osero Earn

https://docs.osero.org/
Admin
Osero Earn is a stablecoin yield infrastructure layer that enables platforms to offer...
Tokens:17,497
Snippets:197
Trust Score:4.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Configure Osero Examples

Source: https://docs.osero.org/osero-sdk/reference/examples

Install the Osero SDK examples and configure your environment variables, particularly the PRIVATE_KEY. Ensure you use a disposable wallet with small amounts for testing as examples broadcast real transactions.

```bash
pnpm install

cp examples/.env.example examples/.env
```

--------------------------------

### Install ethers v6 adapter

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Install the ethers v6 library if you prefer using it for signing and broadcasting transactions.

```bash
pnpm add ethers
```

--------------------------------

### Install Osero Client with npm

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Use this command to add `@osero/client` and `viem` to your project using npm.

```bash
npm install @osero/client viem
```

--------------------------------

### Install Osero Client with yarn

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Use this command to add `@osero/client` and `viem` to your project using yarn.

```bash
yarn add @osero/client viem
```

--------------------------------

### Install Osero Client with pnpm

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Use this command to add `@osero/client` and `viem` to your project using pnpm.

```bash
pnpm add @osero/client viem
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

Perform an HTTP GET request on the current page URL with the `ask` query parameter to dynamically query the documentation. Use this when the answer is not explicitly present or for clarification.

```http
GET https://docs.osero.org/osero-sdk/core-concepts/balance-helpers.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.osero.org/osero-sdk/getting-started/quick-start

Perform an HTTP GET request on the current page URL with the `ask` query parameter to dynamically query documentation. The question should be specific and self-contained.

```http
GET https://docs.osero.org/osero-sdk/getting-started/quick-start.md?ask=<question>
```

--------------------------------

### Example .env File for RPC URLs

Source: https://docs.osero.org/osero-sdk/reference/configuration

A sample `.env` file demonstrating how to define RPC URLs for different networks, typically used with environment variable-based configuration.

```bash
RPC_URL_MAINNET=https://eth.llamarpc.com
RPC_URL_BASE=https://mainnet.base.org
RPC_URL_ARBITRUM=https://arb1.arbitrum.io/rpc
RPC_URL_OPTIMISM=https://mainnet.optimism.io
RPC_URL_UNICHAIN=https://mainnet.unichain.org
```

--------------------------------

### Query Documentation with HTTP GET

Source: https://docs.osero.org/osero-sdk/reference/examples

Perform an HTTP GET request on the current page URL with the `ask` query parameter to dynamically query the documentation. The question should be specific and self-contained. Use this when the answer is not explicitly present, for clarification, or to retrieve related sections.

```http
GET https://docs.osero.org/osero-sdk/reference/examples.md?ask=<question>
```

--------------------------------

### Query Documentation

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Perform an HTTP GET request with the `ask` query parameter to dynamically query the documentation for specific information.

```http
GET https://docs.osero.org/osero-sdk/getting-started/installation.md?ask=<question>
```

--------------------------------

### Verify Osero Client Installation

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Import the `SUPPORTED_CHAIN_IDS` from the Osero client to verify that the SDK has been installed correctly and resolves properly.

```typescript
import { SUPPORTED_CHAIN_IDS } from '@osero/client';

console.log(SUPPORTED_CHAIN_IDS);
// [1, 10, 130, 8453, 42161]
```

--------------------------------

### Ethers v6: Mint USDS on Base

Source: https://docs.osero.org/osero-sdk/reference/examples

This example mirrors the viem equivalent for minting USDS on Base, but utilizes an ethers v6 `Wallet` for the transaction.

```bash
pnpm --filter @osero/examples ethers:mint-usds
```

--------------------------------

### Query Documentation Index

Source: https://docs.osero.org/osero-product

Perform an HTTP GET request to the documentation index with the 'ask' parameter to get a direct answer to a question. The question should be specific and self-contained.

```http
GET https://docs.osero.org/readme.md?ask=<question>
```

--------------------------------

### Query Osero Documentation via HTTP GET

Source: https://docs.osero.org/osero-product/introduction

Use this method to dynamically query the documentation. Perform an HTTP GET request on the current page URL with the 'ask' query parameter. The question should be specific and in natural language. Use this when the answer is not explicitly present, for clarification, or to retrieve related sections.

```http
GET https://docs.osero.org/osero-product/introduction.md?ask=<question>
```

--------------------------------

### Dry Run: Inspect Execution Plan on Base

Source: https://docs.osero.org/osero-sdk/reference/examples

Builds and inspects an `ExecutionPlan` for minting sUSDS on the Base network without broadcasting any transactions. This is a good initial step to verify your SDK setup.

```bash
pnpm --filter @osero/examples dry-run:inspect-plan
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.osero.org/osero-sdk/reference/error-handling

Perform an HTTP GET request to the current page URL with the `ask` query parameter to get specific information not directly present on the page. The question should be specific, self-contained, and in natural language.

```HTTP
GET https://docs.osero.org/osero-sdk/reference/error-handling.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.osero.org/osero-product/overview/sky-savings-rate

Perform an HTTP GET request to query documentation dynamically using the `ask` query parameter. This is useful when the answer is not explicitly present on the current page or requires clarification.

```http
GET https://docs.osero.org/osero-product/overview/sky-savings-rate.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.osero.org/osero-sdk/core-concepts

Perform an HTTP GET request to the current page URL with the `ask` query parameter to dynamically query the documentation. The question should be specific and self-contained. Use this when the answer is not explicitly present, for clarification, or to retrieve related sections.

```HTTP
GET https://docs.osero.org/osero-sdk/core-concepts.md?ask=<question>
```

--------------------------------

### Osero SDK Mental Model: Round Trip Example

Source: https://docs.osero.org/osero-sdk/reference/examples

Illustrates the interaction between the three Osero SDK layers: preview helpers for quoting, actions for building wallet-agnostic plans, and adapters for broadcasting through a wallet. It also shows balance tracking.

```typescript
import { OseroClient, getTokenBalances } from '@osero/client';
import { mintSUsds, redeemSUsds, previewMintSUsds } from '@osero/client/actions';
import { sendWith } from '@osero/client/viem';

// 1. Create the client
const client = OseroClient.create({ transports: { 8453: http(RPC_URL_BASE) } });

// 2. Preview: quote expected sUSDS before building a plan
const quote = await previewMintSUsds(client, { chainId: 8453, amount });
console.log('Expected sUSDS:', quote.value);

// 3. Read balances before
const before = await getTokenBalances(client, { chainId: 8453, account });

// 4. Mint: action → plan → send
await mintSUsds(client, { chainId: 8453, amount, sender: account })
  .andThen(sendWith(wallet));

// 5. Read balances after mint
const afterMint = await getTokenBalances(client, { chainId: 8453, account });

// 6. Redeem: reverse the flow
const susdsBalance = afterMint.value.sUSDS;
await redeemSUsds(client, { chainId: 8453, amount: susdsBalance, sender: account })
  .andThen(sendWith(wallet));

// 7. Final balances
const final = await getTokenBalances(client, { chainId: 8453, account });
```

--------------------------------

### Query Osero Documentation Dynamically

Source: https://docs.osero.org/osero-product/features

Use this GET request to query the documentation dynamically when information is not directly available on the page. The question should be specific and self-contained.

```http
GET https://docs.osero.org/osero-product/features.md?ask=<question>
```

--------------------------------

### Query Osero Documentation Dynamically

Source: https://docs.osero.org/osero-product/overview

Perform an HTTP GET request to the current page URL with the 'ask' query parameter to dynamically query the documentation. Use this when the answer is not explicitly present, for clarification, or to retrieve related sections.

```http
GET https://docs.osero.org/osero-product/overview.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.osero.org/osero-product/features/backing-transparency

Perform an HTTP GET request to query documentation dynamically. Use the 'ask' query parameter with a specific, self-contained question in natural language. This mechanism is useful when information is not explicitly present, requires clarification, or when retrieving related documentation.

```http
GET https://docs.osero.org/osero-product/features/backing-transparency.md?ask=<question>
```

--------------------------------

### Common Pattern: Quote then Execute Minting sUSDS

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Demonstrates the common pattern of first previewing a transaction to get an estimated output, displaying it to the user, and then executing the action upon user confirmation. This involves using both preview and action functions, along with formatting utilities.

```typescript
import { previewMintSUsds, mintSUsds } from '@osero/client/actions';
import { parseUnits, formatUnits } from 'viem';

const amount = parseUnits('100', 6);

// 1. Get a quote
const quote = await previewMintSUsds(client, { chainId: 8453, amount });
if (quote.isErr()) return; // handle error

// 2. Show the user (format from 18-decimal sUSDS)
console.log(`You will receive approximately ${formatUnits(quote.value, 18)} sUSDS`);

// 3. On user confirmation, execute
const result = await mintSUsds(client, {
  chainId: 8453,
  amount,
  sender: wallet.account.address,
}).andThen(sendWith(wallet));
```

--------------------------------

### Access Chain and Contract Data with Osero SDK

Source: https://docs.osero.org/osero-sdk/core-concepts/supported-chains

Import and use constants and functions from '@osero/client' to access supported chain IDs, chain information, PSM contract addresses, and token addresses. Use `PSM_ADDRESSES` with a chain ID to get the PSM address, and `getToken` with a chain ID and token symbol to retrieve token details.

```typescript
import {
  SUPPORTED_CHAIN_IDS,
  CHAINS,
  PSM_ADDRESSES,
  getToken,
} from '@osero/client';

// List of all supported chain IDs
console.log(SUPPORTED_CHAIN_IDS);
// [1, 10, 130, 8453, 42161]

// PSM contract address on Base
console.log(PSM_ADDRESSES[8453].psm);

// sUSDS token address on Ethereum Mainnet
console.log(getToken(1, 'sUSDS').address);

// USDC token address on Arbitrum One
console.log(getToken(42161, 'USDC').address);
```

--------------------------------

### Get Single Token Balance

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

Use `getTokenBalance` to fetch the balance of a specific token (USDC, USDS, or sUSDS) on a given chain. The `token` parameter accepts the token symbol as a string.

```typescript
import { getTokenBalance } from '@osero/client';

const result = await getTokenBalance(client, {
  chainId: 42161,
  account: '0xYourAddress',
  token: 'sUSDS',
});

if (result.isOk()) {
  console.log('sUSDS balance:', result.value);
}
```

--------------------------------

### Get All Token Balances

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

Use `getTokenBalances` to retrieve the balances of USDC, USDS, and sUSDS in a single call. Ensure the client and chain ID are correctly provided. The result is a ResultAsync object containing a map of token symbols to their raw bigint balances.

```typescript
import { getTokenBalances } from '@osero/client';

const result = await getTokenBalances(client, {
  chainId: 8453,
  account: '0xYourAddress',
});

if (result.isOk()) {
  console.log('USDC:', result.value.USDC);   // raw bigint, 6 decimals
  console.log('USDS:', result.value.USDS);   // raw bigint, 18 decimals
  console.log('sUSDS:', result.value.sUSDS); // raw bigint, 18 decimals
}
```

--------------------------------

### Viem: Mint USDS on Base

Source: https://docs.osero.org/osero-sdk/reference/examples

Demonstrates minting USDS on the Base network using a single approve and PSM3 swap, facilitated by viem.

```bash
pnpm --filter @osero/examples viem:mint-usds
```

--------------------------------

### Viem: Mint sUSDS on Ethereum Mainnet

Source: https://docs.osero.org/osero-sdk/reference/examples

Shows how to mint sUSDS on Ethereum Mainnet through a four-transaction `MultiStepExecution` using viem.

```bash
pnpm --filter @osero/examples viem:mint-susds-mainnet
```

--------------------------------

### Using sendWith Adapter

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Demonstrates how to use the `sendWith` adapter to execute an `ExecutionPlan` with a provided wallet. The adapter handles broadcasting and confirmation of transactions.

```typescript
// The adapter is the same regardless of plan shape
const result = await mintSUsds(client, request).andThen(sendWith(wallet));
```

--------------------------------

### Viem: Redeem sUSDS on Base

Source: https://docs.osero.org/osero-sdk/reference/examples

Illustrates the process of redeeming sUSDS back to USDC on the Base network using viem.

```bash
pnpm --filter @osero/examples viem:redeem-susds
```

--------------------------------

### Mint sUSDS with viem Adapter

Source: https://docs.osero.org/osero-sdk/getting-started/quick-start

Initializes the OseroClient with a custom RPC transport for Base. Builds the ExecutionPlan for minting sUSDS from USDC on Base, which involves an Erc20ApprovalRequired plan for L2s. Pipes the plan through the viem adapter to broadcast transactions and waits for confirmation. Handles potential failures using ResultAsync.

```typescript
import { OseroClient } from '@osero/client';
import { mintSUsds } from '@osero/client/actions';
import { sendWith } from '@osero/client/viem';
import { createWalletClient, http, parseUnits } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const privateKey = process.env.PRIVATE_KEY as `0x${string}` | undefined;
if (!privateKey) throw new Error('Set PRIVATE_KEY before sending transactions');

// 1. Create the OseroClient with a custom transport for Base
const client = OseroClient.create({
  transports: {
    8453: http('https://mainnet.base.org'),
  },
});

// 2. Create a viem WalletClient
const wallet = createWalletClient({
  account: privateKeyToAccount(privateKey),
  chain: base,
  transport: http('https://mainnet.base.org'),
});

// 3. Mint 100 USDC worth of sUSDS on Base
const result = await mintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6), // USDC has 6 decimals
  sender: wallet.account.address,
}).andThen(sendWith(wallet));

if (result.isErr()) {
  console.error(result.error.name, result.error.message);
  process.exit(1);
}

console.log('sUSDS minted in tx', result.value.txHash);
```

--------------------------------

### Mint USDS with ethers v6 Adapter

Source: https://docs.osero.org/osero-sdk/getting-started/quick-start

Sets up an ethers provider and signer for broadcasting transactions. Initializes the OseroClient, configuring transports for read calls. Builds the ExecutionPlan for minting USDS on Arbitrum and pipes it through the ethers v6 adapter for broadcasting. Logs the transaction hash on success.

```typescript
import { OseroClient } from '@osero/client';
import { mintUsds } from '@osero/client/actions';
import { sendWith } from '@osero/client/ethers';
import { JsonRpcProvider, Wallet, parseUnits } from 'ethers';
import { http } from 'viem';

const privateKey = process.env.PRIVATE_KEY;
if (!privateKey) throw new Error('Set PRIVATE_KEY before sending transactions');

const rpcUrl = 'https://arb1.arbitrum.io/rpc';

// 1. Set up an ethers provider and signer for broadcasting.
const provider = new JsonRpcProvider(rpcUrl);
const signer = new Wallet(privateKey, provider);

// 2. Create the OseroClient. Even when broadcasting through ethers, the
//    SDK still uses a viem transport internally for read calls (PSM
//    previews, LitePSM fees, etc.), so transports are configured the
//    same way as with the viem adapter.
const client = OseroClient.create({
  transports: {
    42161: http(rpcUrl),
  },
});

// 3. Mint 1000 USDC worth of USDS on Arbitrum
const result = await mintUsds(client, {
  chainId: 42161,
  amount: parseUnits('1000', 6),
  sender: await signer.getAddress(),
}).andThen(sendWith(signer));

if (result.isOk()) {
  console.log('USDS minted in tx', result.value.txHash);
}
```

--------------------------------

### Common Pattern: Quote then Execute

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Demonstrates the common pattern of previewing an action, displaying the expected output to the user, and then executing the action upon user confirmation.

```APIDOC
### Common pattern: quote then execute

A common pattern in production integrations is to preview first, display the expected output to the user, and then execute the action only after the user confirms:

```typescript
import { previewMintSUsds, mintSUsds } from '@osero/client/actions';
import { parseUnits, formatUnits } from 'viem';

const amount = parseUnits('100', 6);

// 1. Get a quote
const quote = await previewMintSUsds(client, { chainId: 8453, amount });
if (quote.isErr()) return; // handle error

// 2. Show the user (format from 18-decimal sUSDS)
console.log(`You will receive approximately ${formatUnits(quote.value, 18)} sUSDS`);

// 3. On user confirmation, execute
const result = await mintSUsds(client, {
  chainId: 8453,
  amount,
  sender: wallet.account.address,
}).andThen(sendWith(wallet));
```
```

--------------------------------

### Create and Export a Reusable OseroClient Instance

Source: https://docs.osero.org/osero-sdk/reference/configuration

Demonstrates creating a single instance of OseroClient and exporting it for reuse throughout an application, promoting efficiency and consistent configuration.

```typescript
// config/osero.ts
import { OseroClient } from '@osero/client';
import { http } from 'viem';

export const oseroClient = OseroClient.create({
  transports: {
    8453: http(process.env.RPC_URL_BASE!),
  },
});
```

--------------------------------

### Send Execution Plan with viem WalletClient

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Use the `sendWith` adapter for viem to route an execution plan to a viem WalletClient for signing and broadcasting.

```typescript
import { sendWith } from '@osero/client/viem';
await plan.andThen(sendWith(viemWallet));
```

--------------------------------

### Dry-run with flattenExecutionPlan

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Shows how to use `flattenExecutionPlan` to inspect all individual transactions within an `ExecutionPlan` without interacting with a wallet. This is useful for debugging and user pre-flight checks.

```typescript
import { flattenExecutionPlan } from '@osero/client';
import { mintSUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const planResult = await mintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6),
  sender: '0xYourAddress',
});

if (planResult.isOk()) {
  const txs = flattenExecutionPlan(planResult.value);
  for (const tx of txs) {
    console.log('Operation:', tx.operation);
    console.log('To:', tx.to);
    console.log('Data:', tx.data);
  }
  // No wallet interaction has happened
}
```

--------------------------------

### Configure OseroClient Using Environment Variables for RPC URLs

Source: https://docs.osero.org/osero-sdk/reference/configuration

Set up OseroClient by reading RPC URLs from environment variables, which is a common pattern for managing sensitive or environment-specific configurations.

```typescript
import { OseroClient } from '@osero/client';
import { http } from 'viem';

const client = OseroClient.create({
  transports: {
    1:     http(process.env.RPC_URL_MAINNET!),
    10:    http(process.env.RPC_URL_OPTIMISM!),
    130:   http(process.env.RPC_URL_UNICHAIN!),
    8453:  http(process.env.RPC_URL_BASE!),
    42161: http(process.env.RPC_URL_ARBITRUM!),
  },
});
```

--------------------------------

### Viem: Round Trip USDC to sUSDS on Base

Source: https://docs.osero.org/osero-sdk/reference/examples

Performs a full round trip from USDC to sUSDS and back to USDC on the Base network using viem. It also demonstrates balance tracking with `getTokenBalances` and `getSUsdsBalance`.

```bash
pnpm --filter @osero/examples viem:roundtrip
```

--------------------------------

### Unit Test Actions with Mock PublicClient

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Construct an OseroClient with a mock or forked PublicClient to unit-test actions without requiring a live chain or real wallet. This is useful for testing the plan generation logic.

```typescript
import { OseroClient } from '@osero/client';
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

// In tests: inject a mock or forked client
const mockClient = OseroClient.create({
  transports: {
    8453: http('http://localhost:8545'), // local anvil fork
  },
});

const result = await mintSUsds(mockClient, {
  chainId: 8453,
  amount: parseUnits('100', 6),
  sender: testAddress,
});

// Assert on the plan without broadcasting
expect(result.isOk()).toBe(true);
```

--------------------------------

### Handle Token Amounts with Viem Utilities

Source: https://docs.osero.org/osero-sdk/core-concepts/supported-chains

Use `parseUnits` from viem to convert human-readable token amounts into the raw `bigint` format expected by the SDK, specifying the token's decimals. Use `formatUnits` to convert raw `bigint` balances back into human-readable strings for display, also specifying the token's decimals.

```typescript
import { parseUnits, formatUnits } from 'viem';

// Preparing an input amount
const amount = parseUnits('100', 6); // 100 USDC → 100_000_000n

// Formatting an output amount for display
const humanReadable = formatUnits(rawSUsdsBalance, 18);
```

--------------------------------

### Configure OseroClient with Fallback Transports

Source: https://docs.osero.org/osero-sdk/reference/configuration

Use viem's `fallback` transport to provide multiple HTTP endpoints for a chain, ensuring resilience. Public transports are rate-limited and unsuitable for production.

```typescript
import { http, webSocket, fallback } from 'viem';

const client = OseroClient.create({
  transports: {
    8453: fallback([
      http('https://base-mainnet.g.alchemy.com/v2/YOUR_KEY'),
      http('https://mainnet.base.org'),
    ]),
  },
});
```

--------------------------------

### Create OseroClient with Transports and Default Slippage

Source: https://docs.osero.org/osero-sdk/reference/configuration

Configure OseroClient with specific HTTP transports for multiple chains and set a default slippage tolerance. Always provide custom transports for production.

```typescript
import { OseroClient } from '@osero/client';
import { http } from 'viem';

const client = OseroClient.create({
  transports: {
    1:     http('https://eth.llamarpc.com'),
    10:    http('https://mainnet.optimism.io'),
    130:   http('https://mainnet.unichain.org'),
    8453:  http('https://mainnet.base.org'),
    42161: http('https://arb1.arbitrum.io/rpc'),
  },
  defaultSlippageBps: 10, // 0.10% — overrides the 5 bps default
});
```

--------------------------------

### Mint USDC to USDS Action

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Converts USDC to USDS using the appropriate PSM for the specified chain. Ensure the client and wallet are correctly configured before execution.

```typescript
import { mintUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const result = await mintUsds(client, {
  chainId: 8453,           // Base
  amount: parseUnits('500', 6), // 500 USDC
  sender: '0xYourAddress',
}).andThen(sendWith(wallet));
```

--------------------------------

### Ethers v6: Round Trip USDC to sUSDS on Base

Source: https://docs.osero.org/osero-sdk/reference/examples

Executes a complete round trip from USDC to sUSDS and back to USDC on the Base network, using an ethers v6 `Wallet`.

```bash
pnpm --filter @osero/examples ethers:roundtrip
```

--------------------------------

### Preview sUSDS Minting Output

Source: https://docs.osero.org/osero-sdk/getting-started/quick-start

Retrieves a quote for the expected output amount of sUSDS before building or sending any transaction. This preview helper only requires chainId and amount, and does not need a sender address or wallet.

```typescript
import { previewMintSUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const quote = await previewMintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6),
});

if (quote.isOk()) {
  console.log('Expected sUSDS output:', quote.value); // raw bigint
}
```

--------------------------------

### Directing Output to a Different Address

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Explains how to use the optional `receiver` field in actions to direct the output token to an address different from the sender.

```APIDOC
## Directing output to a different address

All actions accept an optional `receiver` field. When set, the output token is delivered to `receiver` rather than `sender`:

```typescript
const result = await mintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6),
  sender: userWallet.address,
  receiver: custodyAddress,  // sUSDS lands here
}).andThen(sendWith(wallet));
```
```

--------------------------------

### Preview Minting sUSDS

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Previews the expected output amount for minting sUSDS from USDC. This helper function does not require a sender address and returns a raw bigint wrapped in a ResultAsync. It's useful for displaying estimated amounts to users before they confirm a transaction.

```typescript
import { previewMintSUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const quote = await previewMintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6), // 100 USDC
});

if (quote.isOk()) {
  // Display expected output to user before asking them to sign
  console.log('Expected sUSDS:', quote.value);
}
```

--------------------------------

### Preview Mint sUSDS

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Previews the amount of sUSDS expected when minting with USDC. This helper does not require a sender address and does not broadcast transactions.

```APIDOC
## previewMintSUsds

**Direction:** USDC → sUSDS

```typescript
import { previewMintSUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const quote = await previewMintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6), // 100 USDC
});

if (quote.isOk()) {
  // Display expected output to user before asking them to sign
  console.log('Expected sUSDS:', quote.value);
}
```
```

--------------------------------

### Shorthand Helpers for Single Token Balances

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

For common use cases, utilize the shorthand helpers `getUsdcBalance`, `getUsdsBalance`, and `getSUsdsBalance` to concisely retrieve the balance of a specific token.

```typescript
import { getUsdcBalance, getUsdsBalance, getSUsdsBalance } from '@osero/client';

const usdc = await getUsdcBalance(client, { chainId: 8453, account });
const usds = await getUsdsBalance(client, { chainId: 8453, account });
const susds = await getSUsdsBalance(client, { chainId: 8453, account });
```

--------------------------------

### Format Token Balances with Decimals

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

When displaying token balances, use the correct decimal precision for each token. USDC uses 6 decimals, while USDS and sUSDS use 18 decimals. The `formatUnits` function from `viem` can be used for this.

```typescript
import { formatUnits } from 'viem';

if (result.isOk()) {
  const formattedUSDC = formatUnits(result.value.USDC, 6);
  const formattedUSDS = formatUnits(result.value.USDS, 18);
  const formattedSUSDS = formatUnits(result.value.sUSDS, 18);
}
```

--------------------------------

### Send Execution Plan with ethers v6 Signer

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Use the `sendWith` adapter for ethers v6 to route an execution plan to an ethers Signer for signing and broadcasting.

```typescript
import { sendWith } from '@osero/client/ethers';
await plan.andThen(sendWith(ethersSigner));
```

--------------------------------

### Configure Confirmation Waits for Transactions

Source: https://docs.osero.org/osero-sdk/reference/configuration

Set the number of block confirmations required before a transaction promise resolves. This is configured on the adapter using `sendWith`, not during client creation.

```typescript
import { sendWith } from '@osero/client/viem';

// Wait for 2 block confirmations before resolving
const result = await mintUsds(client, request).andThen(
  sendWith(wallet, { confirmations: 2 })
);
```

--------------------------------

### TypeScript Configuration for ESM (bundler)

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Configure your tsconfig.json for bundler module resolution, suitable for projects using Vite, esbuild, or webpack.

```json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}
```

--------------------------------

### redeemUsds

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Redeems USDS for USDC via the PSM. This is the reverse operation of `mintUsds`.

```APIDOC
## redeemUsds

### Description
Redeems USDS for USDC via the PSM. The reverse of `mintUsds`.

### Method
`redeemUsds(client, request)`

### Parameters
#### Request Body
- **chainId** (number) - Required - One of the supported chain IDs
- **amount** (bigint) - Required - Input amount in the input token's native decimals
- **sender** (`0x${string}`) - Required - The wallet that pays the input token
- **receiver** (`0x${string}`) - Optional - Recipient of the output token. Defaults to sender
- **slippageBps** (number) - Optional - Slippage tolerance in basis points. Defaults to client config (5 bps)
- **referralCode** (bigint) - Optional - See "Referral code" below. Defaults to `0n`.

### Request Example
```typescript
import { redeemUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const result = await redeemUsds(client, {
  chainId: 42161,          // Arbitrum One
  amount: parseUnits('500', 18), // USDS has 18 decimals
  sender: '0xYourAddress',
}).andThen(sendWith(wallet));
```

### Response
Returns a `ResultAsync<ExecutionPlan, ActionError>` that you pipe into `sendWith` to execute.
```

--------------------------------

### Handling CancelError

Source: https://docs.osero.org/osero-sdk/reference/error-handling

Use this case when the user rejects a wallet prompt, such as clicking 'Reject' in MetaMask. This indicates a user-initiated cancellation of the operation.

```typescript
case 'CancelError':
  // Show a "Transaction cancelled" message to the user
  break;
```

--------------------------------

### Mint sUSDS to a Different Receiver Address

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Shows how to use the optional `receiver` field in an action to direct the output tokens to an address different from the sender. This is useful for custody or other specific scenarios.

```typescript
const result = await mintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6),
  sender: userWallet.address,
  receiver: custodyAddress,  // sUSDS lands here
}).andThen(sendWith(wallet));
```

--------------------------------

### mintUsds

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Converts USDC to USDS via the Sky PSM. This action routes through different implementations on Ethereum Mainnet and L2s.

```APIDOC
## mintUsds

### Description
Converts USDC to USDS via the Sky PSM. On Ethereum Mainnet this routes through Sky's `UsdsPsmWrapper`; on L2s it routes through the Spark PSM3.

### Method
`mintUsds(client, request)`

### Parameters
#### Request Body
- **chainId** (number) - Required - One of the supported chain IDs
- **amount** (bigint) - Required - Input amount in the input token's native decimals
- **sender** (`0x${string}`) - Required - The wallet that pays the input token
- **receiver** (`0x${string}`) - Optional - Recipient of the output token. Defaults to sender
- **slippageBps** (number) - Optional - Slippage tolerance in basis points. Defaults to client config (5 bps)
- **referralCode** (bigint) - Optional - See "Referral code" below. Defaults to `0n`.

### Request Example
```typescript
import { mintUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const result = await mintUsds(client, {
  chainId: 8453,           // Base
  amount: parseUnits('500', 6), // 500 USDC
  sender: '0xYourAddress',
}).andThen(sendWith(wallet));
```

### Response
Returns a `ResultAsync<ExecutionPlan, ActionError>` that you pipe into `sendWith` to execute.
```

--------------------------------

### Mint USDC to sUSDS Action

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Converts USDC to sUSDS. This action may involve multiple steps on Ethereum Mainnet, requiring careful handling of the two-phase execution.

```typescript
import { mintSUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const result = await mintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6),
  sender: '0xYourAddress',
}).andThen(sendWith(wallet));
```

--------------------------------

### mintSUsds

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Converts USDC to sUSDS. This action involves a two-phase process on Ethereum Mainnet and a single swap on L2s.

```APIDOC
## mintSUsds

### Description
Converts USDC to sUSDS. On L2s, a single PSM3 swap delivers sUSDS directly. On Ethereum Mainnet, this is a two-phase `MultiStepExecution`: USDC → USDS via the `UsdsPsmWrapper`, then USDS → sUSDS via the ERC-4626 sUSDS vault.

### Method
`mintSUsds(client, request)`

### Parameters
#### Request Body
- **chainId** (number) - Required - One of the supported chain IDs
- **amount** (bigint) - Required - Input amount in the input token's native decimals
- **sender** (`0x${string}`) - Required - The wallet that pays the input token
- **receiver** (`0x${string}`) - Optional - Recipient of the output token. Defaults to sender
- **slippageBps** (number) - Optional - Slippage tolerance in basis points. Defaults to client config (5 bps)
- **referralCode** (bigint) - Optional - See "Referral code" below. Defaults to `0n`.

### Request Example
```typescript
import { mintSUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const result = await mintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6),
  sender: '0xYourAddress',
}).andThen(sendWith(wallet));
```

### Response
Returns a `ResultAsync<ExecutionPlan, ActionError>` that you pipe into `sendWith` to execute.
```

--------------------------------

### TypeScript Configuration for ESM (NodeNext)

Source: https://docs.osero.org/osero-sdk/getting-started/installation

Configure your tsconfig.json for NodeNext module resolution to ensure compatibility with ESM packages.

```json
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022"
  }
}
```

--------------------------------

### Erc20Approval and Erc20ApprovalRequired Types

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Defines structures for handling ERC-20 approvals required before a main transaction. Erc20ApprovalRequired contains a list of approvals and the original transaction.

```typescript
type Erc20Approval = {
  readonly token: `0x${string}`;
  readonly spender: `0x${string}`;
  readonly amount: bigint;
  readonly byTransaction: TransactionRequest; // the actual `approve` tx
};

type Erc20ApprovalRequired = {
  readonly __typename: 'Erc20ApprovalRequired';
  readonly approvals: readonly Erc20Approval[];
  readonly originalTransaction: TransactionRequest; // the gated main tx
};
```

--------------------------------

### getTokenBalances

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

Reads all three canonical token balances (USDC, USDS, sUSDS) in a single call for a given account and chain. Returns a keyed object with raw bigint values.

```APIDOC
## getTokenBalances

### Description
Reads all three canonical token balances (USDC, USDS, sUSDS) in a single call for a given account and chain. Returns a keyed object with raw bigint values.

### Method
`getTokenBalances(client, { chainId, account })`

### Parameters
- `client`: The Osero client instance.
- `chainId` (number): The ID of the chain to query.
- `account` (string): The account address to query balances for.

### Response Example
```json
{
  "USDC": 1000000n, // raw bigint, 6 decimals
  "USDS": 1000000000000000000n, // raw bigint, 18 decimals
  "sUSDS": 1000000000000000000n // raw bigint, 18 decimals
}
```
```

--------------------------------

### Handle Errors from Balance Helpers

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

Balance helpers return a `ResultAsync` object, similar to actions. Handle potential errors such as `UnsupportedChainError` if the chain ID is not recognized, or `UnexpectedError` for RPC failures. Inspect the `.cause` property for more details on unexpected errors.

```typescript
const result = await getSUsdsBalance(client, { chainId: 8453, account });

if (result.isErr()) {
  if (result.error.name === 'UnsupportedChainError') {
    console.error('Chain not supported');
  } else {
    console.error('RPC error:', result.error.cause);
  }
}
```

--------------------------------

### Flatten Execution Plan for Custom Broadcasting

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Flatten an execution plan into its underlying transactions to feed them into a custom broadcasting pipeline, such as a relayer, bundler, or batcher.

```typescript
if (planResult.isOk()) {
  const txs = flattenExecutionPlan(planResult.value);
  for (const tx of txs) {
    // Your own sending logic: relayer, bundler, batcher, etc.
    await myBroadcaster.send(tx);
  }
}
```

--------------------------------

### Track Balance Deltas

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

To track changes in token balances, such as after a mint or redeem operation, read balances before and after the transaction. This allows for calculating the exact delta for each token.

```typescript
const before = await getTokenBalances(client, { chainId: 8453, account });

// ... execute mintSUsds ...

const after = await getTokenBalances(client, { chainId: 8453, account });

if (before.isOk() && after.isOk()) {
  const usdcSpent = before.value.USDC - after.value.USDC;
  const susdsReceived = after.value.sUSDS - before.value.sUSDS;
  console.log(`Spent ${formatUnits(usdcSpent, 6)} USDC`);
  console.log(`Received ${formatUnits(susdsReceived, 18)} sUSDS`);
}
```

--------------------------------

### Full Switch Pattern for Error Handling

Source: https://docs.osero.org/osero-sdk/reference/error-handling

Implement a comprehensive error handling strategy using a switch statement on `result.error.name`. This pattern allows for specific user feedback based on the type of Osero error encountered.

```typescript
import { mintUsds } from '@osero/client/actions';
import { sendWith } from '@osero/client/viem';

const result = await mintUsds(client, request).andThen(sendWith(wallet));

if (result.isErr()) {
  switch (result.error.name) {
    case 'CancelError':
      showToast('Transaction cancelled.');
      break;
    case 'ValidationError':
      showToast(`Invalid input: ${result.error.message}`);
      break;
    case 'UnsupportedChainError':
      showToast('Please switch to a supported network.');
      break;
    case 'TransactionError':
      showToast(`Transaction failed. View on explorer: ${result.error.link}`);
      break;
    case 'SigningError':
    case 'UnexpectedError':
      showToast('Something went wrong. Please try again.');
      console.error(result.error.cause);
      break;
  }
  return;
}

showToast(`Success! Transaction: ${result.value.txHash}`);
```

--------------------------------

### Handling UnsupportedChainError

Source: https://docs.osero.org/osero-sdk/reference/error-handling

Use this case when the provided `chainId` in the request is not present in `SUPPORTED_CHAIN_IDS`. This typically requires prompting the user to switch to a supported network.

```typescript
case 'UnsupportedChainError':
  // Prompt the user to switch to a supported network
  break;
```

--------------------------------

### Handling UnexpectedError

Source: https://docs.osero.org/osero-sdk/reference/error-handling

Use this case for unexpected failures like RPC errors, network timeouts, or unhandled conditions. Inspect the `.cause` property for the underlying error details.

```typescript
case 'UnexpectedError':
  console.error('Unexpected error:', result.error.cause);
  break;
```

--------------------------------

### getUsdcBalance, getUsdsBalance, getSUsdsBalance

Source: https://docs.osero.org/osero-sdk/core-concepts/balance-helpers

Shorthand helper functions to retrieve the balance of a specific canonical token (USDC, USDS, or sUSDS) for a given account and chain. Each returns a raw bigint value.

```APIDOC
## Single-token shorthand helpers

### Description
Shorthand helper functions to retrieve the balance of a specific canonical token (USDC, USDS, or sUSDS) for a given account and chain. Each returns a raw bigint value.

### Methods
- `getUsdcBalance(client, { chainId, account })`
- `getUsdsBalance(client, { chainId, account })`
- `getSUsdsBalance(client, { chainId, account })`

### Parameters
- `client`: The Osero client instance.
- `chainId` (number): The ID of the chain to query.
- `account` (string): The account address to query balances for.

### Response Example
```json
1000000n // raw bigint, 6 decimals (for USDC)
```
```

--------------------------------

### Handling SigningError

Source: https://docs.osero.org/osero-sdk/reference/error-handling

Use this case when the wallet fails to sign a transaction, potentially due to insufficient permissions or a malformed signature. The `result.error.cause` property contains the original error from the wallet.

```typescript
case 'SigningError':
  // result.error.cause has the original error from the wallet
  break;
```

--------------------------------

### Redeem USDS to USDC Action

Source: https://docs.osero.org/osero-sdk/core-concepts/actions

Redeems USDS for USDC, functioning as the reverse of the `mintUsds` action. Ensure the amount is specified in USDS's native 18 decimals.

```typescript
import { redeemUsds } from '@osero/client/actions';
import { parseUnits } from 'viem';

const result = await redeemUsds(client, {
  chainId: 42161,          // Arbitrum One
  amount: parseUnits('500', 18), // USDS has 18 decimals
  sender: '0xYourAddress',
}).andThen(sendWith(wallet));
```

--------------------------------

### MultiStepExecution Type Definition

Source: https://docs.osero.org/osero-sdk/core-concepts/execution-plan

Represents an ordered sequence of execution steps, where each step depends on the previous one. Used for complex operations like multi-phase minting or redeeming.

```typescript
type ExecutionStep = TransactionRequest | Erc20ApprovalRequired;

type MultiStepExecution = {
  readonly __typename: 'MultiStepExecution';
  readonly steps: readonly ExecutionStep[];
};
```

--------------------------------

### Override Default Slippage for a Specific Request

Source: https://docs.osero.org/osero-sdk/reference/configuration

Demonstrates how to set a custom slippage tolerance for an individual transaction, overriding the client's default.

```typescript
await mintSUsds(client, {
  chainId: 8453,
  amount: parseUnits('100', 6),
  sender: '0xYourAddress',
  slippageBps: 20, // 0.20% for this request only
});
```
Tokens:
Raw