Skip to content

BFP-5213: document the withdrawal amount quantum - #301

Closed
kevin-ip wants to merge 2 commits into
mainfrom
kevin/bfp-5213-withdraw-quantum-docs
Closed

kevin-ip wants to merge 2 commits into
mainfrom
kevin/bfp-5213-withdraw-quantum-docs

Conversation

@kevin-ip

@kevin-ip kevin-ip commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

The docs now say that a withdrawal's amountE9 must be a multiple of 10^(9 - decimals) for the asset: 1,000 for USDC, which has 6 decimals. They also say that maxWithdrawQuantityE9 isn't rounded to that multiple and must be rounded down before it's withdrawn. The matching engine is starting to reject other amounts (fireflyprotocol/pro-mono#2125), because on-chain settlement truncates the remainder.

The SDKs are regenerated with apigen. Only the docs and model comments for Asset and WithdrawRequestSignedFields change. Python and Rust go to 1.23.0. TypeScript goes to 2.5.0, set by hand because apigen would have moved it back to 1.23.0.

Merge and publish together with or after fireflyprotocol/pro-mono#2125 is deployed.

🤖 Generated with Claude Code

A withdrawal amount must be a whole number of the asset's smallest
on-chain unit (a multiple of 10^(9 - decimals), 1000 for USDC). The
matching engine rejects other amounts, because settlement truncates the
remainder. maxWithdrawQuantityE9 is not rounded, so clients must round it
down before withdrawing it. Regenerated the SDKs (py/rust 1.23.0, ts
2.5.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread rust/Cargo.toml
name = "bluefin-pro"
repository = "https://github.com/fireflyprotocol/pro-sdk"
version = "1.22.0"
version = "1.23.0"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The version goes to 1.23.0 here and in rust/gen/bluefin_api/Cargo.toml, but rust/Cargo.lock still pins bluefin-pro and bluefin_api at 1.22.0. Earlier bumps updated it (972f367, 2628568). cargo metadata --locked in rust/ already fails on this branch (exit 101). Any --locked/--frozen build fails, and a plain cargo build rewrites the lockfile and leaves the tree dirty. That can also block cargo publish --workspace in crates_publish.yaml. Please commit the regenerated Cargo.lock.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e56ccfd: refreshed rust/Cargo.lock with cargo update --workspace, so bluefin-pro and bluefin_api are locked at 1.23.0 (cargo metadata --locked passes). apigen's version bump doesn't touch the lockfile.

Comment thread ts/sdk/src/api.ts
'accountAddress': string;
/**
* The amount in e9 of the asset that the User will withdraw from their account
* The amount in e9 of the asset that the User will withdraw from their account. Must be a whole number of the asset\'s smallest on-chain unit, i.e. a multiple of 10^(9 - decimals) where decimals is the asset\'s on-chain decimals (1000 for USDC, which has 6 decimals). Other amounts are rejected after the request is accepted, via a failed-command event. Round down to that multiple before submitting, including when withdrawing maxWithdrawQuantityE9.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This only documents the rule. The hand-written helper ProSdk.withdraw(assetSymbol, amountE9) in ts/sdk/src/sdk.ts:656 still signs and posts any amount. It already fetches exchangeInfo and finds the AssetConfig with its decimals, but it only uses that to check that the asset exists. After pro-mono#2125, sdk.withdraw('USDC', asset.maxWithdrawQuantityE9) (for example "12345678901") gets a 202 and the call resolves. The withdrawal is then rejected later, and only a websocket event reports it. The helper has asset.decimals in hand, so it could round down to 10n ** BigInt(9 - decimals) or throw before signing.

asset_symbol: StrictStr = Field(description="Asset symbol of the withdrawn asset", alias="assetSymbol")
account_address: StrictStr = Field(description="The Account Address from which to withdraw assets", alias="accountAddress")
amount_e9: StrictStr = Field(description="The amount in e9 of the asset that the User will withdraw from their account", alias="amountE9")
amount_e9: StrictStr = Field(description="The amount in e9 of the asset that the User will withdraw from their account. Must be a whole number of the asset's smallest on-chain unit, i.e. a multiple of 10^(9 - decimals) where decimals is the asset's on-chain decimals (1000 for USDC, which has 6 decimals). Other amounts are rejected after the request is accepted, via a failed-command event. Round down to that multiple before submitting, including when withdrawing maxWithdrawQuantityE9.", alias="amountE9")

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same gap in Python. BluefinProSdk.withdraw(asset_symbol, amount_e9) in python/sdk/src/bluefin_pro_sdk.py:302 sends amount_e9 without checking it against the asset's decimals. Withdrawing a raw max_withdraw_quantity_e9 returns success, and the rejection arrives later only as an AccountCommandFailureUpdate. Consider validating or rounding down using AssetConfig.decimals from exchange info.

Comment thread resources/trade-api.yaml
Must be a whole number of the asset's smallest on-chain unit, i.e. a multiple of
10^(9 - decimals) where decimals is the asset's on-chain decimals (1000 for USDC,
which has 6 decimals). Other amounts are rejected after the request is accepted,
via a failed-command event. Round down to that multiple before submitting,

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"via a failed-command event" leaves out what integrators need to match on. pro-mono#2125 maps Error::WithdrawPrecision to CommandFailedReason::WithdrawZero, so a non-zero amount like 1,500 comes back as AccountCommandFailureUpdate { failedCommandTypeCode: WITHDRAW, reasonCode: WITHDRAW_ZERO }. A client that handles WITHDRAW_ZERO as "you sent 0" will show the wrong cause. Either document that WITHDRAW_ZERO also covers precision failures (here and on CommandFailureReasonCode in websocket-api.yaml), or add a dedicated reason code in both repos.

Comment thread resources/trade-api.yaml
description: >-
The amount in e9 of the asset that the User will withdraw from their account.
Must be a whole number of the asset's smallest on-chain unit, i.e. a multiple of
10^(9 - decimals) where decimals is the asset's on-chain decimals (1000 for USDC,

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"the asset's on-chain decimals" doesn't say where a client gets that value. The only exposed field is AssetConfig.decimals in exchange-pro-api.yaml:116, and its description is "Default precision for rendering this asset." That reads as a UI precision, not the on-chain unit used for this check. A client could reasonably compute the quantum from some other source. Please point to ExchangeInfo.assets[].decimals here, and update the AssetConfig.decimals description to say it is the on-chain decimals the withdrawal quantum is based on.

Comment thread resources/common.yaml
description: "The maximum quantity that can be withdrawn."
description: >-
The maximum quantity that can be withdrawn, in e9. It is not rounded to the
asset's on-chain decimals; round it down to a multiple of 10^(9 - decimals)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

10^(9 - decimals) only holds for decimals <= 9. The engine uses 10u64.pow(9_u32.saturating_sub(decimals)), so for any asset with more than 9 decimals the quantum is 1. A client that follows the formula literally gets a fractional or negative exponent (10 ** (9 - 18) -> 1e-9, or a BigInt RangeError). Consider saying "10^max(0, 9 - decimals)" here and on amountE9.

Comment thread ts/sdk/package.json
"type": "module",
"types": "./dist/index.d.ts",
"version": "2.4.0"
"version": "2.5.0"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description says this version was set by hand because apigen would have moved TS back to 1.23.0. bump_all_versions takes the base version from rust/Cargo.toml and writes it to ts/sdk/package.json. ts/sdk/openapitools.json npmVersion is also stuck at 1.16.0. So every spec change needs the same manual TS fix, and one missed fix publishes a lower version than 2.5.0, which npm rejects or which looks like a downgrade. It would be more robust to fix this in apigen: give TS its own base version read from package.json, or a fixed major offset, instead of overriding the output by hand each release.

- rust/Cargo.lock: lock bluefin-pro and bluefin_api at 1.23.0 to match the manifests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kevin-ip

kevin-ip commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

Closing: rather than documenting the withdrawal quantum in the SDK specs, the fix belongs in pro-mono (round maxWithdrawQuantityE9 down to the asset's quantum and/or report precision failures distinctly from WITHDRAW_ZERO).

@kevin-ip kevin-ip closed this Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant