Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,16 @@ reference and the API reference for Whisk, the stablecoin payments SDK.

## Status

Being set up. The Mintlify site, the port of the existing docs and the rewrite are
tracked in [the issues](https://github.com/usewhisk/docs/issues):
The site covers `@usewhisk/react` and `@usewhisk/core` 0.3.x and `@usewhisk/cctp` 0.1.x,
ported from the old `apps/docs` and rewritten against the published code. The API
reference tab arrives with the platform's OpenAPI spec.

- [#1](https://github.com/usewhisk/docs/issues/1) Mintlify at `docs.usewhisk.xyz`;
- [#2](https://github.com/usewhisk/docs/issues/2) port the current docs out of
`usewhisk/whisk`;
- [#3](https://github.com/usewhisk/docs/issues/3) rewrite for the new surfaces.
## Run it locally

```bash
pnpm install
npx mint@4.2.993 dev # http://localhost:3000
```

## How the site is built

Expand All @@ -27,7 +30,7 @@ restructure starts with an issue.

```bash
pnpm install # installs the git hooks
pnpm preflight
pnpm preflight # format, shellcheck, Mintlify build, broken links
```

You also need `brew install gitleaks shellcheck`. Read the
Expand Down
86 changes: 86 additions & 0 deletions chains.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
---
title: "Chains"
description: "How Whisk names chains, how the network follows the chain, and which chains you can use."
---

A chain in Whisk is a string id such as `"Base"`, `"Base_Sepolia"` or `"Arc_Testnet"`. The type is `Chain`, and every helper that takes a chain is checked against the registry at compile time:

```ts
import { CHAINS, getChain, isChainId, type Chain } from "@usewhisk/react";

const base = getChain("Base_Sepolia");
console.log(base.label, base.ecosystem, base.network, base.cctpDomain);

const testnets: Chain[] = CHAINS.filter((c) => c.network === "testnet").map(
(c) => c.id,
);

function parseChain(input: string): Chain {
if (!isChainId(input)) throw new Error(`Unknown chain: ${input}`);
return input;
}
```

The registry lives in `@usewhisk/cctp` and is re-exported by `@usewhisk/core` and `@usewhisk/react`. It holds 56 chains: 25 EVM mainnets and their 25 testnets, plus Solana, Stellar and Starknet on mainnet and testnet. Each entry carries the chain's CCTP domain, USDC address, CCTP contracts, default RPCs, explorer and capabilities. The ids are Circle's names for each chain, so a testnet id names its testnet: `Ethereum_Sepolia`, `Avalanche_Fuji`, `Polygon_Amoy_Testnet`, `Solana_Devnet`.

## Common chain ids

| Ecosystem | Mainnet | Testnet | Fast source | Circle forwards the mint |
| --------- | ------------- | ---------------------- | ----------- | ------------------------ |
| EVM | `Ethereum` | `Ethereum_Sepolia` | yes | yes |
| EVM | `Base` | `Base_Sepolia` | yes | yes |
| EVM | `Arbitrum` | `Arbitrum_Sepolia` | yes | yes |
| EVM | `Optimism` | `Optimism_Sepolia` | yes | yes |
| EVM | `Polygon` | `Polygon_Amoy_Testnet` | no | yes |
| EVM | `Avalanche` | `Avalanche_Fuji` | no | yes |
| EVM | `Linea` | `Linea_Sepolia` | yes | yes |
| EVM | `Unichain` | `Unichain_Sepolia` | yes | yes |
| EVM | `World_Chain` | `World_Chain_Sepolia` | yes | yes |
| EVM | `Arc` | `Arc_Testnet` | no | yes |
| Solana | `Solana` | `Solana_Devnet` | yes | yes |
| Stellar | `Stellar` | `Stellar_Testnet` | no | no |
| Starknet | `Starknet` | `Starknet_Sepolia` | yes | no |

"Fast source" means Circle offers Fast Transfer for burns from that chain. "Circle forwards the mint" means Circle's Forwarding Service can submit the mint on that chain. The full list, with domains and every capability, is in the [chain reference](/reference/cctp/chains).

## Network comes from the chain

Every chain id belongs to one network, `"mainnet"` or `"testnet"`, and a transfer runs on the network of its source chain. There is no `mode` setting. The same config can list mainnet and testnet chains together:

```ts whisk.ts
import { createWhiskConfig, evm } from "@usewhisk/react";

export const config = createWhiskConfig({
wallets: [evm({ chains: ["Base", "Base_Sepolia", "Arc", "Arc_Testnet"] })],
chains: ["Base", "Base_Sepolia", "Arc", "Arc_Testnet"],
});
```

`WhiskSend` then offers only destinations on the same network as the selected source chain. A route that mixes the two is refused by `quote` with `NetworkMismatchError` before anything is signed. Circle's attestation service is chosen the same way: Iris mainnet for mainnet chains, the Iris sandbox for testnets.

## Ecosystems

`getChain(id).ecosystem` is one of `"evm"`, `"solana"`, `"stellar"` or `"starknet"` (the `ChainKind` type). The ecosystem decides which wallet factory a chain needs: put a chain in `config.chains` only if the matching factory is in `config.wallets`. See [wallets](/wallets).

USDC has 6 decimals on every chain Whisk supports, with one exception: raw Stellar trustline balances use 7. Amounts you pass to Whisk are decimal strings such as `"10.50"` whatever the chain. See [amounts and units](/concepts/amounts-and-units).

## Fast and Standard

CCTP V2 has two transfer speeds, and the source chain decides which one Whisk uses:

- **Fast.** Circle attests the burn after a few seconds instead of waiting for the source chain to finalize, and charges a fee for it. Whisk uses Fast whenever the source chain offers it.
- **Standard.** Circle attests after the source chain finalizes. On Ethereum and most rollups that settle to it, that takes about 15 to 19 minutes, and on Linea several hours. On chains with fast finality, such as Arc, Avalanche and Polygon, Standard is already quick, which is why Circle offers no Fast Transfer from them.

```ts
import { getChain } from "@usewhisk/react";

const source = getChain("Arbitrum");
const speed = source.capabilities.fastSource ? "Fast" : "Standard";
const forwarded = getChain("Base").capabilities.forwardingDestination;
```

The mint on the destination is submitted by Circle's Forwarding Service when the destination supports it and the source is an EVM chain or Solana. Otherwise the payer connects a wallet on the destination and signs the mint. The fees for each part are in the quote the payer confirms. See [how it works](/concepts/how-it-works) and [quotes and fees](/concepts/quotes-and-fees).

## EVM chains the evm() factory cannot switch to

`evm()` builds its wagmi config from wallet definitions for 36 of the 50 EVM ids. `Cronos`, `Edge`, `Injective`, `Morph`, `Pharos`, `Plasma`, `X_Layer` and their testnets are in the registry, but `evm()` drops them, so the widget cannot switch a wallet to them. To use them, bring your own wagmi config. See [wallets](/wallets#bring-your-own-wagmi-config).
160 changes: 160 additions & 0 deletions concepts/amounts-and-units.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
---
title: Amounts and units
description: How Whisk represents USDC amounts, and how to convert between what payers type and what wallets sign.
---

USDC amounts cross Whisk's API as decimal strings such as `"12.5"` and live inside it as `bigint` subunits, with 6 decimals. Convert with `parseUsdcAmount` and `formatUsdcAmount`, and never put money in a JavaScript `number`.

```ts
import {
USDC_DECIMALS,
formatUsdcAmount,
parseUsdcAmount,
} from "@usewhisk/core";

const subunits = parseUsdcAmount("12.5"); // 12500000n
const display = formatUsdcAmount(subunits); // "12.5"

console.log(USDC_DECIMALS, subunits, display); // 6 12500000n "12.5"
```

## Strings at the edge, bigints inside

| Where | Unit |
| -------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `QuoteParams.amount`, `FeePolicy.value`, refund amounts | Decimal string, such as `"1.50"` |
| `Quote.amountIn`, `amountOut`, `amountBurned`, every `FeeEntry.amount`, `FeeBreakdown.total` | Decimal string, for display |
| `Quote.subunits.*` | `bigint`, 6-decimal subunits |
| `engine.balance()`, `MaxSendable.balance`, `MaxSendable.gasReserve` | `bigint`, 6-decimal subunits |
| `MaxSendable.amount` | Decimal string, ready for `quote` |
| `InflightRecord.amountBurned` | Subunit string, so the record stays JSON |

The strings on a quote are derived from its `subunits`, and `send` signs the subunits. When you need to compare or add amounts, use the `bigint` fields. When you show them, use the strings or `formatUsdcAmount`.

## parseUsdcAmount

`parseUsdcAmount(input)` turns what a payer typed into subunits:

- it trims whitespace and accepts digits with at most one dot and digits on both sides of it: `"5"`, `"0.75"` and `"1000.000001"` parse, `"5."` and `".5"` do not;
- it rejects signs, exponents, commas and anything else (`"-1"`, `"1e3"`, `"1,000"`) with a `ConfigError`;
- it rejects zero, since every transfer must move something;
- digits past the sixth decimal are truncated, not rounded, so the payer is never debited more than they typed: `"1.2345678"` becomes `1234567n`.

`formatUsdcAmount(subunits)` goes the other way and strips trailing zeros: `1500000n` becomes `"1.5"`, `2000000n` becomes `"2"`. It throws on a negative value.

<Tip>
`formatUsdcAmount` gives an exact string, not a localised one. For display
with thousands separators or a fixed number of decimals, format the string
yourself; converting it to a `number` first loses precision on large amounts.
</Tip>

## Doing arithmetic

Do arithmetic on `bigint` subunits, and format once at the end.

```ts
import { formatUsdcAmount, parseUsdcAmount } from "@usewhisk/core";

const price = parseUsdcAmount("19.99");
const quantity = 3n;
const total = price * quantity; // 59970000n

const perPerson = total / 4n; // 14992500n
const remainder = total % 4n; // 0n

console.log(formatUsdcAmount(total), formatUsdcAmount(perPerson), remainder);
// "59.97" "14.9925" 0n
```

`bigint` division rounds toward zero. Decide who gets the remainder before you split an amount between several recipients.

<Warning>
`0.1 + 0.2` is not `0.3` in floating point. A float anywhere between the
payer's input and the signature can move the amount by a subunit or, after a
few operations, more. Whisk's own code has no float math on money, and code
that feeds it should not either.
</Warning>

## Stellar: 7 decimals

Stellar's USDC asset has 7 decimals. CCTP messages always carry 6. Whisk keeps every amount in 6-decimal subunits, including on Stellar, and scales at the edge:

- **Sending from Stellar.** The engine multiplies the burn amount and `maxFee` by 10 when it builds the Soroban call. Circle's contract drops the seventh decimal again to produce the 6-decimal message amount. Because `parseUsdcAmount` already truncates to 6 decimals, no dust is lost.
- **Bridging into Stellar.** The mint multiplies the 6-decimal message amount by 10. The recipient's trustline balance shows the same value with one more decimal place.
- **Same-chain sends on Stellar.** The 6-decimal amount is scaled to 7 when the transfer is submitted.

`engine.balance()` returns `null` on Stellar, so a raw trustline balance only reaches your code when you read it yourself. Convert it with the helpers from `@usewhisk/cctp` before you mix it with Whisk amounts:

```ts
import {
canonicalToStellarSubunits,
stellarSubunitsToCanonical,
} from "@usewhisk/cctp";
import { formatUsdcAmount } from "@usewhisk/core";

const trustlineBalance = 123_456_789n; // 12.3456789 USDC, 7 decimals
const canonical = stellarSubunitsToCanonical(trustlineBalance); // 12345678n

console.log(formatUsdcAmount(canonical), canonicalToStellarSubunits(canonical));
// "12.345678" 123456780n
```

`stellarSubunitsToCanonical` rounds toward zero; the seventh decimal stays in the Stellar account.

## Arc: USDC is the gas token

On Arc, gas is paid in USDC. The same balance appears two ways:

- as Arc's native token, with 18 decimals, which is what gas prices and `maxFeePerGas` are counted in;
- through the USDC ERC-20 contract, with 6 decimals, which is what Whisk reads and transfers.

A payer on Arc spends USDC on both the transfer and its gas, so Whisk keeps some back:

- `send` refuses with `InsufficientBalanceError` when the balance cannot cover the quote's `amountIn` plus a gas reserve.
- `maxSendable` returns the largest amount that leaves the reserve in place.

The reserve is a generous gas limit (100,000 gas for a same-chain send, 400,000 for a bridge) times Arc's current gas price plus 25%, never below Arc's 20 gwei floor, converted from 18 decimals to 6 and rounded up. At the floor that is 0.002 USDC for a send and 0.008 USDC for a bridge. Every transaction Whisk sends on Arc also carries a `maxFeePerGas` at or above that floor, because Arc drops transactions offering less.

```ts
import {
createWhisk,
formatUsdcAmount,
type EvmAdapter,
type ResolvedRecipient,
} from "@usewhisk/core";

declare const adapter: EvmAdapter;
declare const recipient: ResolvedRecipient;

const engine = createWhisk({ chains: ["Arc_Testnet", "Base_Sepolia"] });

const max = await engine.maxSendable({
sourceChain: "Arc_Testnet",
destinationChain: "Base_Sepolia",
recipient,
adapter,
});

if (max) {
console.log(
`Balance ${formatUsdcAmount(max.balance)} USDC, ` +
`kept for gas ${formatUsdcAmount(max.gasReserve)} USDC, ` +
`sendable ${max.amount} USDC`,
);
}
```

`maxSendable` also subtracts every fee the payer covers, so its `amount` can go straight into `quote`. It returns `null` when the source wallet is not EVM, since Whisk does not read Solana, Stellar or Starknet balances.

On every other EVM chain gas is a separate native token, the reserve is zero, and Whisk does not check the payer's gas balance; the wallet does.

## Related

<CardGroup cols={2}>
<Card title="Quotes and fees" href="/concepts/quotes-and-fees">
The subunits behind every quote.
</Card>
<Card title="Types reference" href="/reference/core/types">
`Quote`, `QuoteSubunits` and `MaxSendable` field by field.
</Card>
</CardGroup>
Loading
Loading