Skip to content

docs(sui-indexer): add coin management notes and confirm no race condition #327

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rcc999 merged 6 commits into from
Jan 29, 2026
Merged

docs(sui-indexer): add coin management notes and confirm no race condition #327

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
02fae13
docs(sui-indexer): add coin management notes and confirm no race cond…
Rcc999 Jan 28, 2026
eaad5c9
Update packages/sui-indexer/README.md
Rcc999 Jan 29, 2026
9f5a9a8
Update packages/sui-indexer/src/ika_client.ts
Rcc999 Jan 29, 2026
9006254
Merge branch 'master' into rayane/coin-race-condition-docs
Rcc999 Jan 29, 2026
2d37861
Resolved prettier ci issue
Rcc999 Jan 29, 2026
505ac3b
Merge branch 'master' into rayane/coin-race-condition-docs
Rcc999 Jan 29, 2026
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
14 changes: 14 additions & 0 deletions packages/sui-indexer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,20 @@ UTXOs are stored in the `nbtc_utxos` table in the D1 database.

**Key Concept:** The database acts as a cache of the on-chain state. The `SuiIndexer` ensures this cache stays synchronized with the canonical state on the Sui blockchain.

## IKA Coin Management

We use IKA coins to pay for presign/sign requests. The coin selection logic lives in `packages/lib/src/coin-ops.ts`.

### How it works

1. `fetchAllIkaCoins()` grabs all IKA coins for the signer
2. `selectCoins()` picks coins to hit the target amount (takes first 80, then sorts by balance if needed)
3. `prepareCoin()` merges them if we need multiple coins

### Concurrency

The process is not safe for parallel workload. See the doc comment in `fetchAllIkaCoins`.

## API

This package exposes [Cloudflare RPC](../../README.md#cloudflare-rpc).
Expand Down
3 changes: 3 additions & 0 deletions packages/sui-indexer/src/ika_client.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,9 @@ export class IkaClientImp implements IkaClient {
return this.ikaConfig.objects.ikaDWalletCoordinator.objectID;
}

// Fetches all IKA coins for an address. Used with prepareCoin() to select & merge coins.
// NOTE: this can't be used in a parallel workload. Currently, the workers only run one cron at a time with one processSolvedRedeems process.
// So no parallel coin selection happens.
// TODO: we should have maxCoins?: number limit
async fetchAllIkaCoins(owner: string): Promise<CoinStruct[]> {
const allCoins: CoinStruct[] = [];
Expand Down