You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rewrites the manual deposit flow in the design document. Users no longer have to pass a Solana transaction signature: a new deposit_sol endpoint reads the balance of the deposit address, queues it for a sweep, and ckSOL is minted once the sweep is finalized. Several transfers below the minimum deposit amount are therefore credited together, and deposits from exchanges only need the deposit address.
The design is motivated by #206, which shows how the current consolidation strands a deposit and loops on resubmission when a deposit address keeps a remainder below the rent-exempt minimum. The sweep leaves exactly that threshold on every deposit address, the largest deposit of a batch pays the transaction fee, the fee is read from the finalized transaction rather than assumed, and expired or failed sweeps are dropped and re-queued by the caller instead of being retried by the minter.
The section includes a sequence diagram and a worked example with two deposits showing the fees at each stage and what each user ends up with. The consolidation, fee, parameter constraint and API sections are aligned with the new flow. The README and the Candid interface will follow with the implementation.
…sweep
The manual deposit flow no longer asks the user for a Solana transaction
signature. A new deposit_sol endpoint reads the balance of the deposit
address, queues it for a sweep that leaves the rent exemption threshold on
the address, and mints ckSOL only once the sweep is finalized, using the fee
read from the finalized transaction. Sweeps that expire or fail are dropped
and the caller queues a new one, so the minter never retries on its own.
Includes a sequence diagram and a worked example with two deposits showing
the fees at every stage, and aligns the consolidation, fee, parameter
constraint and API sections with the new flow.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This PR replaces signature-based manual deposits with balance-based SOL sweeps and deferred minting.
Changes:
Adds deposit_sol and deposit_status.
Documents batching, rent handling, fees, finalization, failures, and retries.
Updates related API, constraints, diagrams, and examples.
File
Summary and findings
docs/design.md
Documents the new sweep lifecycle. Unresolved critical issues cover automatic-flow exclusivity, fee accounting, and balance underflow; moderate and nit issues cover API naming, absent-status handling, fee documentation, RPC coverage, and example calculations.
Allow concurrent deposits when validating sweep post-balance
docs/design.md:349
sweepable is captured before submission, so a new transfer can arrive before this transaction executes. The transaction then correctly leaves the rent threshold plus that new transfer; requiring every post-balance to equal the threshold would reject a valid concurrent deposit and conflicts with the concurrency guarantee above. Validate the queued debit and post_balance >= threshold, leaving the excess for a later sweep.
Sweep expiry conflicts with shared finalization state machine
docs/design.md:354
This expiry rule conflicts with the finalization section that this flow is said to reuse: §3.2.2 currently expires unknown transactions after 150 slots/blocks and moves them to PendingResubmission (lines 472–494). A sweep would therefore be both dropped here and resubmitted there, and slot-based expiry has the race this text warns about. Update the shared state machine or explicitly exclude sweeps and define the block-height source.
This issue also appears on line 356 of the same file.
deposit_sol has replaced process_deposit, but this paragraph still names the required cycles field process_deposit_required_cycles. That leaves the new API advertising a stale endpoint-specific name; rename it to a deposit_sol-specific field or explicitly document it as a deliberate compatibility alias in the design and get_minter_info.
This issue also appears on line 653 of the same file.
Document getBalance RPC cost and endpoint
docs/design.md:351
getBalance is now required by the deposit flow, but it is absent from the RPC endpoint list in §3.1 and from the response-size/cost table in §3.3.2. Add its cost assumptions so the stated 2.1B charge and 45B consolidation fee are reproducible from the design.
…idation trigger
A finalized sweep whose transaction fetch fails is retried on the
finalization timer, and one whose balance sanity check fails is
quarantined with the existing mechanism instead of minted. Withdrawals
no longer trigger a consolidation, since the main account always covers
the minted supply.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The sweep timer is described as running at the withdrawal-processing frequency, but §3.2.1 proposes 10 seconds while §3.1.4 describes consolidation as a roughly 10-minute timer. Because the sweep is explicitly the consolidation transaction, this leaves the batching latency and operational load ambiguous; reconcile the two schedules before implementation.
Restrict sweeps to addresses with queued sweep records
docs/design.md:420
The generic consolidation section still says the timer processes any unconsolidated address until all deposits are consolidated. In the balance-sweep flow only addresses with a queued sweep have a recorded owner and amount; sweeping an address that has never called deposit_sol moves SOL to the main account without a pending mint or credit. Restrict the candidate set to queued sweep records and update the timer description accordingly.
Describe manual fees using the finalized fee share
docs/design.md:525
This summary also hard-codes the manual fee at 5,000 lamports, although the sweep accounting below uses the fee actually charged by the finalized transaction. If the fee schedule changes, this public fee summary becomes inaccurate; describe the charge as the finalized fee share and identify 5,000 lamports only as the current-schedule value.
Base per-deposit fees on the finalized transaction fee
docs/design.md:564
This section hard-codes the per-deposit fee as ceil(5000 * k / k) = 5000, while §3.1.3 deliberately reads the actual finalized transaction fee so fee-schedule changes cannot over-mint. If the actual fee differs from 5000 * k, this fee summary and the stated user accounting are wrong; express the share as ceil(actual_fee / k) and present 5,000 lamports only as the current-schedule example.
The new public endpoint is deposit_sol, but this paragraph still exposes its required cycles under the old process_deposit_required_cycles name. That makes the design's public API point callers to a field for the removed signature-based flow; rename it to a deposit_sol-specific field or explicitly document that the old name is retained for compatibility.
► docs/design.md Update design document with numerous structural and flow changes to manual and automated deposit flows, finalization, and consolidation processes
Define consolidation completion without requiring empty addresses
docs/design.md:384
After identifying manual consolidation with the sweep here, the generic rule below still says to scan any “unconsolidated address” until all deposits are consolidated. A sweep intentionally leaves 890,880 lamports on every address, so that condition can never become false if interpreted literally and can cause repeated work. Define consolidation over queued sweep records or sweepable amounts and stop once each record is finalized, rather than over nonempty addresses.
Include all RPC costs and retries in cycle funding
docs/design.md:566
The new flow adds a paid getBalance call and uses getBlockHeight for block-height-based expiry, but neither appears in the endpoint cost table or in this 45B worst-case list. Status polling and transaction-fetch retries can also execute more than once. As written, the advertised process_deposit_required_cycles can underfund the required RPC work; add measured costs and a bounded retry/charging rule before fixing this fee.
Remove or mark the deferred update_balance endpoint
docs/design.md:656
The API list still presents update_balance as an exposed endpoint even though §3.1.2 now warns that the automated flow is not implemented and is deferred. As written, the public API section advertises a flow that this design says does not exist. Remove it from the current endpoint list or mark it explicitly as a future/outdated endpoint.
Since users deposit funds in dedicated deposit addresses, the ckSOL minter's funds are spread across multiple addresses, making withdrawals inconvenient. Therefore, a consolidation mechanism is introduced that transfers the funds from deposit addresses to the main address of the ckSOL minter. The general flow for submitting a transaction is shown in the following figure.
Since users deposit funds in dedicated deposit addresses, the ckSOL minter's funds are spread across multiple addresses, making withdrawals inconvenient. Therefore, a consolidation mechanism is introduced that transfers the funds from deposit addresses to the main address of the ckSOL minter. In the manual flow of [Section 3.1.3](#313-manual-flow), the consolidation is the sweep itself: ckSOL is minted only once the consolidation transaction is finalized. The general flow for submitting a transaction is shown in the following figure.
All transactions are created on a timer. Since a transaction must contain a recent block hash, such a block hash must be obtained first: A `getSlot` call is used to get a recent slot, followed by a `getBlock` call to retrieve block details, in particular the block hash, for the slot received in the first step. Note that it is possible that there is no block for a certain slot, in which case `getSlot` needs to be called again, followed by another call to `getBlock`. The figure only shows the happy path of one call each. Given a recent block hash, the transaction is built, obtaining an EdDSA signature for each transfer to be made within that transaction. Once the transaction is signed and serialized, it is sent to the SOL RPC canister, which forwards it to the RPC providers.
All transactions are created on a timer. Since a transaction must contain a recent block hash, such a block hash must be obtained first: A `getSlot` call is used to get a recent slot, followed by a `getBlock` call to retrieve block details, in particular the block hash, for the slot received in the first step. Note that it is possible that there is no block for a certain slot, in which case `getSlot` needs to be called again, followed by another call to `getBlock`. The figure only shows the happy path of one call each. Given a recent block hash, the transaction is built, obtaining an EdDSA signature for each transfer to be made within that transaction. The block height of the block whose hash is used is persisted together with the transaction: a block hash is valid for 150 blocks after that height, and this *last valid block height* is what expiry is later checked against. Once the transaction is signed and serialized, it is sent to the SOL RPC canister, which forwards it to the RPC providers.
A user may issue a request to retrieve a particular transaction and mint ckSOL based on that transaction manually. This manual flow serves two purposes: First, it enables a user to get ckSOL more quickly, as there is no initial waiting time. Second, if the `update_balance` call exhausted the quota, the manual flow can be used to retrieve the transaction corresponding to a SOL transfer to the deposit address, which will then result in the minting of ckSOL, and replenish the quota of the deposit address for future automatic lookups.
A user who has transferred SOL to their deposit address asks the ckSOL minter to *sweep* that address. The user does not identify individual Solana transactions: the ckSOL minter reads the balance of the deposit address, moves it to its main account, and mints ckSOL once that sweep is finalized. As a consequence, several transfers that are each below the minimum deposit amount are credited together once their sum exceeds it, and deposits from centralized exchanges, which typically do not show the transaction signature to the user, need nothing but the deposit address.
The reason will be displayed to describe this comment to others. Learn more.
It's not super clear from this paragraph that the manual flow starts after the user has already called get_deposit_address (and then transferred SOL to that deposit address), would it make sense to add it? Or refer to some earlier subsection that is common to both the automatic and manual flow (although I don't think such a subsection currently exists).
The manual flow is triggered by calling `process_deposit` with the user's account (principal ID and subaccount) and the signature identifying the transaction as parameters. This endpoint requires cycles to be attached. As specified in [Section 3.3.2](#332-cksol-minter-fees), **1T cycles** must be attached to the call.
**Request.** The flow is triggered by calling `deposit_sol` with the user's account (principal ID and subaccount) as parameters. The principal may differ from the caller's, so that a frontend or another canister can pay for a user's deposit, but it must not be the anonymous principal. The endpoint requires cycles to be attached; the required amount is exposed as `process_deposit_required_cycles` in `get_minter_info` and, as explained below, most of it is refunded. At most one deposit per account can be in flight: if a deposit for the given account is queued, swept, or finalized but not yet minted, the call fails with an error carrying the id of the in-flight deposit and refunds all attached cycles without contacting the SOL RPC canister. Only a deposit that is minted or dropped allows a new sweep of the same account. If the latest deposit of the account is quarantined, the call is rejected with an error carrying the id of the quarantined deposit, since the SOL of that deposit has reached the main account without being credited, and the account remains rejected until manual intervention resolves the quarantined deposit. The account is reserved before the first inter-canister call, so that concurrent calls for the same account cannot both pass this check, and the reservation is released on every error path.
As far as the **automatic deposit fee** is concerned, if we assume a total cost of 0.418T cycles (10 × 4.3B for the maximum 10 `getSignaturesForAddress` calls plus 50 × 7.5B for the `getTransaction` calls), the cost in SOL is 0.418 XDR = 0.602 USD = 0.00602 SOL at 1 SOL = 100 USD. A threshold signature costs 26.2B cycles, which is later required for the consolidation transaction. The cost is 0.0262 XDR = 0.0377 USD = 0.000377 SOL. Additionally, there is a fee of 5000 lamports for the consolidation transaction on Solana. The total cost is therefore 0.006402 SOL. Overcharging slightly, a reasonable choice for the fee is **0.01 SOL**.
The **manual deposit fee** must only cover the cost of the signature in the consolidation transaction where the funds are transferred to the main account. This cost is 5000 lamports. Adding again a safety margin, the manual deposit fee could be set to 10,000 lamports, i.e., **0.00001 SOL**.
The **manual deposit fee** is not a parameter but the depositor's share of the fee of the sweep transaction that consolidates the deposit, i.e., `ceil(5000 * k / k) = 5000` lamports, read from the finalized transaction as described in [Section 3.1.3](#313-manual-flow). In addition, the depositor leaves the rent exemption threshold of 890,880 lamports on the deposit address the first time it is swept. The cycles consumed by the manual flow are charged to the caller of `deposit_sol`: the cost of the `getBalance` call, roughly 2.1B cycles given its small response, plus the **deposit consolidation fee**. The latter must cover the threshold signature of 26.2B cycles and, in the worst case of a sweep containing a single deposit, all the RPC calls of the sweep and finalization timers, i.e., `getSlot`, `getBlock`, `sendTransaction`, `getSignatureStatuses`, and `getTransaction`, for about 16.3B cycles. A deposit consolidation fee of **45B cycles** covers this worst case for a single attempt. Retries of the `getTransaction` call after a failure, as well as the status checks of the finalization timer, which are batched for all in-flight transactions, are not charged to the caller: the ckSOL minter accepts the risk of spending more cycles than it received for a deposit, as the alternative of an attempt budget adds complexity for a failure that should be rare.
The reason will be displayed to describe this comment to others. Learn more.
I believe this 45B cycles assumes a single call for each of the RPC methods - retrying a handful of them may still be fine, but if more retries are required, the cost may go over 45B.
The withdrawal and consolidation flows result in the submission of a transaction, which is then in the `Submitted` state. The status of submitted transactions is checked on a timer as outlined above. If a transaction reaches the confirmation status `finalized`, there are two cases: If the transaction was finalized successfully, i.e., without errors, the transaction transitions to the state `Succeeded` and its ID is stored permanently. If there was an error, the transaction transitions to the state `Failed` and is stored in its entirety so that it can be analyzed what happened. Ideally, no transaction ever ends up in this state. However, it is possible for transactions to fail, for example by attempting to withdraw SOL to a program account, which is not allowed. As there is no reimbursement flow, the user's funds would be stuck in this case. Storing the whole failed transaction ensures that the funds are not lost and appropriate actions may be taken when such transactions are encountered.
If the transaction expires, i.e., it is unknown after 150 blocks, it enters the `Pending resubmission` state. A different timer fetches transactions from this state, following the transaction submission flow to submit it again, at which point the transaction is back in the `Submitted` state.
If the transaction expires, i.e., it is unknown after 150 blocks, it enters the `Pending resubmission` state. A different timer fetches transactions from this state, following the transaction submission flow to submit it again, at which point the transaction is back in the `Submitted` state. Sweep transactions of the manual flow are the exception: an expired sweep is never resubmitted but dropped, as described in [Section 3.1.3](#313-manual-flow), since nothing has been minted for it yet and the user can simply queue a new sweep.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites the manual deposit flow in the design document. Users no longer have to pass a Solana transaction signature: a new
deposit_solendpoint reads the balance of the deposit address, queues it for a sweep, and ckSOL is minted once the sweep is finalized. Several transfers below the minimum deposit amount are therefore credited together, and deposits from exchanges only need the deposit address.The design is motivated by #206, which shows how the current consolidation strands a deposit and loops on resubmission when a deposit address keeps a remainder below the rent-exempt minimum. The sweep leaves exactly that threshold on every deposit address, the largest deposit of a batch pays the transaction fee, the fee is read from the finalized transaction rather than assumed, and expired or failed sweeps are dropped and re-queued by the caller instead of being retried by the minter.
The section includes a sequence diagram and a worked example with two deposits showing the fees at each stage and what each user ends up with. The consolidation, fee, parameter constraint and API sections are aligned with the new flow. The README and the Candid interface will follow with the implementation.
🤖 Generated with Claude Code