docs: add deployment guide and fix issues found on staging by gregorydemay · Pull Request #263 · dfinity/cksol

gregorydemay · 2026-10-08T13:05:08Z

DEFI-3029

Adds a deployment guide (docs/deployment.md) for the ckSOL minter, ledger and index, and fixes the issues found while doing a full deposit and withdrawal round trip and a deposit stress test on the staging minter (Devnet).

Guide:

Minter addresses on Solana, derived offline for production and staging.
Initialization arguments of the minter, ledger and index.
How to create durable nonce accounts with the minter as nonce authority.
How to deposit SOL and follow the deposit status.

Fixes:

Finalized sweeps were never credited. getTransaction was sent with a 2 MB response size estimate, which the SOL RPC canister prices at about 220B cycles on the fiduciary subnet, while the minter attaches 50B. Every call was rejected before reaching a provider and surfaced as "Inconsistent RPC results". getTransaction and getSignatureStatuses now use the SOL RPC canister's default estimates (about 3.2B and 10.7B cycles for 256 signatures). Verified on staging: the stuck deposit was minted after the upgrade.
Sweeps could expire before reaching the chain. During a stress test of 50 deposits, two sweeps were rejected by all providers with BlockhashNotFound and their 18 deposits were dropped: the blockhash, fetched at finalized commitment, was already close to expiry when the transactions were sent (on Devnet, 150 blocks last about 36 s). Sweeps now fetch their blockhash at confirmed commitment and run the preflight simulation at the same commitment. The expiry check keeps using finalized. Details in the stress test report.
effective_transaction_fee is removed from the withdrawal status. It was always null; the user pays the fixed withdrawal_fee, while the Solana transaction fee is paid by the minter.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…nd getSignatureStatuses The 2 MB response size estimate made the SOL RPC canister charge about 220B cycles per call on the 34-node fiduciary subnet, while the minter attached only 50B cycles for `getTransaction`. Every call was rejected before reaching a provider, so finalized sweeps were never credited. The SOL RPC canister's per-method defaults fit the minter's responses: 10 KiB for `getTransaction` and 256 bytes per signature for `getSignatureStatuses`. With them the calls cost about 3.2B and 10.7B cycles (256 signatures) on mainnet. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…l status The field was always `None`. A user pays the fixed `withdrawal_fee`, which is already visible as the difference between the burned amount and the transferred amount, while the Solana transaction fee is paid by the minter and shared by the withdrawals of a batch. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Copilot

🟡 Changes recommended

The new address test fails enforced Clippy checks, and the critical RPC configuration fix lacks regression coverage.

3 open findings

Remove redundant static lifetimes from test constants · New
Add regression test for getTransaction response size config · New
Add regression test for getSignatureStatuses response size config · New

What changed in this PR

Adds ckSOL deployment guidance and fixes staging issues affecting sweep finalization and withdrawal status reporting.

Changes:

Uses SOL RPC default response-size estimates.
Removes the unused withdrawal transaction-fee field.
Documents deployment, nonce-account setup, and deposit testing.

File	Description
`docs/deployment.md`	Adds deployment and testing guide.
`libs/types/src/lib.rs`	Updates withdrawal status type.
`minter/cksol_minter.did`	Updates the Candid interface.
`minter/src/address/tests.rs`	Verifies deployed minter addresses.
`minter/src/constants.rs`	Removes obsolete response-size constant.
`minter/src/rpc/mod.rs`	Uses endpoint-specific RPC defaults.
`minter/src/state/mod.rs`	Updates finalized withdrawal responses.
`minter/src/state/tests.rs`	Updates state expectations.
`minter/src/withdraw/tests.rs`	Updates withdrawal expectations.

🧠 Review effort: Balanced

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

Copilot

🔵 Needs a closer look

The critical RPC configuration fix lacks regression coverage preventing the oversized estimate from being reintroduced.

2 open findings

Add regression test for getSignatureStatuses response size config
Add regression test for getTransaction response size config

1 resolved since last review

Remove redundant static lifetimes from test constants

🧠 Review effort: Balanced

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

A sweep fetched its blockhash at finalized commitment, so the block was already old when the minter learned about it. Together with the getBlock calls and the threshold signatures, the transaction could reach the RPC providers after the blockhash expired. On Devnet, where 150 blocks last about 36 s, two sweeps were rejected with BlockhashNotFound and their 18 deposits were dropped. The sweep now fetches the slot and the block at confirmed commitment and runs the preflight simulation at the same commitment, since a finalized simulation would not know the newer blockhash. The monitor keeps fetching the current block height at finalized commitment for the expiry check. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

The production-critical response-size fixes lack automated regression coverage.

2 open findings

Add regression test for getSignatureStatuses response size config
Add regression test for getTransaction response size config

🧠 Review effort: Balanced

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

…ocks The sweep now fetches its block at confirmed commitment and the monitor at finalized commitment, so the getBlock request carries a commitment that the mocks must match. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…the default response size estimate A 2 MB estimate made the SOL RPC canister charge more cycles than the minter attaches, so every getTransaction call was rejected. These tests fail if an explicit estimate is set again on either call. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

Regression tests should assert both affected RPC calls retain default response-size estimates.

0 open findings

2 resolved since last review

Add regression test for getSignatureStatuses response size config
Add regression test for getTransaction response size config

🧠 Review effort: Balanced

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

Copilot

🟢 Approval recommended

The production fixes are consistently implemented with focused regression and integration coverage.

0 open findings

🧠 Review effort: Balanced

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

zeropath-ai · 2026-10-08T15:09:09Z

✅ No security or compliance issues detected. Reviewed everything up to ec3970c.

Security Overview

🔎 Scanned files: 15 changed file(s)
🔗 Scan Link: https://zeropath.com/app/repositories/58f1cdfe-c0c2-41c1-8d28-3d6efcaf3266?scanId=e1b4f02f-cba9-4890-8eaa-728d471b6104&codeScanTypes=PrScan&tab=issues&detectionTypes=traditional,businessLogic,customRule,IAC,SECRETS,CICD,EOL,uncategorized

Detected Code Changes

Change Type	Relevant files
Enhancement	► integration_tests/src/fixtures.rs Update imports and block commitment handling for get_block/get_slot/getTransaction usage in tests ► minter/src/deposit/sweep/timer.rs Introduce SWEEP_BLOCKHASH_COMMITMENT and use Confirmed commitment for recent block and transaction submission ► minter/src/deposit/sweep/timer/tests.rs Add tests asserting commitment handling for getSlot/getBlock/sendTransaction ► minter/src/monitor/mod.rs Add CommitmentLevel import for block height checks ► minter/src/monitor/tests.rs Update tests to use Finalized commitment in get_recent_block/get_slot/get_block calls ► minter/src/rpc/mod.rs Adapt get_transaction/get_signature_statuses to reflect removal of response_size_estimate setting and add commitment parameter to get_recent_block ► minter/src/rpc/tests.rs Update tests to pass CommitmentLevel where required and extend tests for commitment-aware behavior ► minter/src/state/mod.rs Support building sol_rpc_client with builder and remove immediate build; expose sol_rpc_client_builder ► minter/src/constants.rs Remove MAX_HTTP_OUTCALL_RESPONSE_BYTES constant and related usage ► minter/src/address/tests.rs Update imports and test to reflect new public key derivation/public key types and derive_mainnet/offline test block ► minter/cksol_minter.did Remove effective_transaction_fee field from TxFinalizedStatus::Success ► minter/src/rpc/tests.rs Adjust test imports for new GetBlockCommitmentLevel, GetSlotParams, GetTransactionParams, etc. ► minter/src/state/tests.rs Update test expectations to align with removal of effective_transaction_fee field

mbjorkqvist

Thanks @gregorydemay! For the PR title, perhaps something like fix: would be more accurate than docs:, since this PR also contains production code changes.

mbjorkqvist · 2026-10-08T15:25:40Z

-pub const MAX_HTTP_OUTCALL_RESPONSE_BYTES: u64 = 2_000_000;
-
 /// Cycles to attach for `getTransaction` RPC calls.
 pub const GET_TRANSACTION_CYCLES: u128 = 50_000_000_000;


🤖 With the 2 MB estimate gone, the attached cycles no longer match what the calls cost. GET_SIGNATURE_STATUSES_CYCLES (1T, line 50) was sized for the 2 MB reservation, while a call now costs about 10.7B for 256 signatures and 2.3B for one. check_transaction_statuses sends up to MAX_CONCURRENT_RPC_CALLS = 10 of them at once, so the minter needs about 10T of spare cycles above its freezing threshold for a round that actually costs at most ~107B; a minter running low would fail these calls and stall finalization, even though the unused part is refunded. GET_TRANSACTION_CYCLES (50B against ~3.2B) is harmless but has lost its rationale. Lowering both, with comments tied to the default estimates and some headroom for the SOL RPC canister doubling the reservation on an oversized response, would keep them meaningful.

mbjorkqvist · 2026-10-08T15:25:40Z

+
+## Test
+
+### Deposit SOL


🤖 The description mentions a full deposit and withdrawal round trip on staging, but the Test section covers deposits only. Adding the withdrawal steps (icrc2_approve on the ledger, the withdrawal call, and following its status) would make the guide cover what was verified.

mbjorkqvist · 2026-10-08T15:25:40Z

+| `deposit_sol_fee`             | 45B cycles            | Covers the threshold signature and the RPC calls of a sweep containing a single deposit.        |
+| `deposit_sol_required_cycles` | 1T cycles             | Must be at least `GET_BALANCE_CYCLES` (10B) plus `deposit_sol_fee`; unused cycles are refunded. |
+| `minimum_deposit_amount`      | 0.02 SOL (20,000,000) | Must be at least twice the rent exemption threshold plus the fee of one signature.              |
+| `withdrawal_fee`              | 0.001 SOL (1,000,000) | Covers `getAccountInfo`, `sendTransaction`, `getSignatureStatuses` and the threshold signature. |


🤖 Once #260 lands, withdrawals are no longer finalized with getSignatureStatuses but with a getAccountInfo read of the nonce account and a getTransaction call for the outcome, so this rationale becomes stale. Whichever of the two PRs lands second could update it, together with §3.3.2 of the design.

gregorydemay and others added 8 commits October 8, 2026 11:24

test(minter): derive mainnet minter addresses offline

de78a8e

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs: add deployment guide with minter address and init arguments

282167b

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs: build ledger logo from SVG and fix staging token name

08c2010

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs: add index canister initialization arguments

568fa68

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs: document how to deposit SOL and check the deposit status

5a1e991

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs: document how to create durable nonce accounts

17b6ce8

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Copilot AI balanced review requested due to automatic review settings October 8, 2026 13:05

Copilot started reviewing on behalf of gregorydemay October 8, 2026 13:05 View session

style(minter): remove redundant static lifetimes in address tests

13a2899

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Comment thread minter/src/address/tests.rs Outdated

Comment thread minter/src/rpc/mod.rs

Comment thread minter/src/rpc/mod.rs

Copilot AI balanced review requested due to automatic review settings October 8, 2026 13:08

Copilot started reviewing on behalf of gregorydemay October 8, 2026 13:09 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 8, 2026 14:09

Copilot started reviewing on behalf of gregorydemay October 8, 2026 14:09 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

mbjorkqvist mentioned this pull request Oct 8, 2026

feat(minter): finalize withdrawals from their nonce accounts #260

Merged

Copilot AI balanced review requested due to automatic review settings October 8, 2026 15:01

Copilot started reviewing on behalf of gregorydemay October 8, 2026 15:02 View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

Copilot AI balanced review requested due to automatic review settings October 8, 2026 15:05

Copilot started reviewing on behalf of gregorydemay October 8, 2026 15:05 View session

gregorydemay marked this pull request as ready for review October 8, 2026 15:07

gregorydemay requested a review from a team as a code owner October 8, 2026 15:07

gregorydemay requested a review from mbjorkqvist October 8, 2026 15:08

gregorydemay requested a review from eichhorl October 8, 2026 15:08

Copilot AI reviewed Oct 8, 2026

View reviewed changes

This was referenced Oct 8, 2026

docs: add ledger index canister IDs to deployment table #173

Merged

chore: staging ledger and minter init args #147

Closed

mbjorkqvist approved these changes Oct 8, 2026

View reviewed changes

Navigation Menu

Repository navigation

docs: add deployment guide and fix issues found on staging - #263

docs: add deployment guide and fix issues found on staging#263
gregorydemay wants to merge 12 commits into
mainfrom
gdemay/DEFI-3029-deployment

gregorydemay commented Oct 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

zeropath-ai Bot commented Oct 8, 2026

Uh oh!

mbjorkqvist left a comment

Uh oh!

mbjorkqvist Oct 8, 2026

Uh oh!

mbjorkqvist Oct 8, 2026

Uh oh!

mbjorkqvist Oct 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

gregorydemay commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

zeropath-ai Bot commented Oct 8, 2026

Uh oh!

mbjorkqvist left a comment

Choose a reason for hiding this comment

Uh oh!

mbjorkqvist Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

mbjorkqvist Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

mbjorkqvist Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gregorydemay commented Oct 8, 2026 •

edited

Loading