@circle-fin/unified-balance-kit — spend() parameter shape is hard to find

[Mky67]

While integrating the standalone Unified Balance Kit package into ShieldFi, it took two failed attempts to find the correct parameter shape for spend():

Used amountIn → got "Invalid amount 'unknown': Amount must be a numeric string..."
Passed from as an array ([{ adapter }], no chain specified) → got "Failed to initialize wallet client for chain undefined: No chain definition found for blockchain: undefined"
Working shape: from: { adapter, allocations: { amount, chain } }, field name amount (not amountIn)

Finding the difference took a while since a clear usage example for the standalone package wasn't easy to locate.

Suggestion: A more discoverable, copy-pasteable example of the standalone Unified Balance Kit's spend() signature (especially the from/allocations shape) in the npm README or Arc Docs would improve the dev experience.

[osr21]

Dug into the published types for @circle-fin/unified-balance-kit@1.4.0 (spend() takes SpendParams re-exported from @circle-fin/provider-gateway-v1), and I think there's a useful clarification here: amountIn isn't actually the wrong field — the SDK supports two different amount modes, and the errors you hit come from mixing them.

The two valid shapes

Mode A — explicit per-source allocations (what you landed on):

await spend(context, {
  from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } }, // amount lives inside each allocation
  to:   { adapter: destAdapter, chain: 'Avalanche' },
  token: 'USDC',
})

Mode B — adapter-only, provider auto-allocates (top-level amountIn):

await spend(context, {
  from: { adapter },        // no allocations
  amountIn: '50',           // required in this mode; provider resolves per-chain allocations
  to:   { adapter: destAdapter, chain: 'Avalanche' },
  token: 'USDC',
})

This is straight from the type docs:

• SpendParams.amountIn — "Required when sources are adapter-only (no explicit allocations). The provider resolves per-chain allocations at burn-intent creation time."
• SpendSource.allocations — "When omitted the provider computes allocations automatically using the amountIn field on SpendParams."

So the failures line up:

• amountIn → "Invalid amount 'unknown'": amountIn used alongside allocations (or without a valid decimal string) — in Mode A the amount must be inside allocations, not top-level.
• from: [{ adapter }] with no chain/amountIn → "chain undefined": that's Mode B without the amountIn the provider needs to resolve allocations, so it can't derive a source chain.

from does accept a single source or an array (for multi-chain spends) — both are valid; the array just needs each source fully specified for the mode you're using.

On the discoverability ask (agree)

Worth noting the v1.4.0 README does already show the Mode A shape (from: { adapter, allocations: { amount, chain } }) in several examples — but it doesn't spell out the amountIn-vs-allocations mode split, which is exactly the trap you hit. A short "two ways to specify the amount" callout next to the spend() signature would prevent this.

One routing note: this kit is a standalone Circle stablecoin-kit (its source/README live outside circlefin/arc-node, which is node-operator scoped), so the doc change would need to land in the package README / Circle developer docs rather than this repo — but capturing the repro here is a good signal.

[Mky67]

Thanks for digging into the type docs — that's a much clearer explanation than I had. Makes sense now: we were mixing Mode A and Mode B (had amountIn set alongside allocations on the first attempt, then dropped both on the second, which is why the provider couldn't derive a source chain). Good to confirm Mode A is the correct, stable shape for what we're doing.

And fair point on the routing — I'll flag the "two amount modes" callout to the package README / dev docs rather than expecting a change here. Appreciate you taking the time to trace it through the actual types.