From ee2bae8891d62c19e1037232b66cec2f499d3bb0 Mon Sep 17 00:00:00 2001 From: forcodedancing Date: Wed, 25 Sep 2024 10:05:57 +0800 Subject: [PATCH] chore: add docs for payment settlement, freeze and resume (#469) --- .../core-concept/billing-payment.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/bnb-greenfield/core-concept/billing-payment.md b/docs/bnb-greenfield/core-concept/billing-payment.md index 7bed59bf49..92f5af0fcf 100644 --- a/docs/bnb-greenfield/core-concept/billing-payment.md +++ b/docs/bnb-greenfield/core-concept/billing-payment.md @@ -74,6 +74,49 @@ It will also provide a possibility for projects to sponsor the storage and bandw For more details, you can refer to the [BEP of the paymaster](https://github.com/bnb-chain/BEPs/pull/362). +### Force Settlement, Freeze and Resume + +If a user doesn't deposit for a long time, his previous deposit may be +all used up for the stored objects. Greenfield has a forced settlement +mechanism to ensure enough funds are secured for further service fees. + +There are two configurations, `ReserveTime` and `ForcedSettleTime`. + +Let's take an example where the `ReserveTime` is 7 days and the `ForcedSettleTime` is 1 day. +If a user wants to store an object at the price of +approximately $0.1 per month($0.00000004/second), he must reserve fees +for 7 days in the buffer balance, which is `$0.00000004 * 7 * 86400 = +$0.024192`. If the user deposits is $1 initially, the stream payment +record will be as below: + +- **CRUD Timestamp**: 100; + +- **Static Balance**: $0.975808; + +- **Netflow Rate**: -$0.00000004/sec; + +- **Buffer Balance**: $0.024192. + +After 10000 seconds, the dynamic balance of the user will be `0.975808 - 10000 * 0.00000004 = 0.975408`. + +After 24395200 seconds(approximately 282 days), the dynamic balance of +the user will become negative. Users should have some alarms for such +events that remind them to supply more funds in time. + +If no more funds are supplied and the dynamic balance plus buffer +balance is under the forced settlement threshold, the account will be +forcibly settled. All payment streams of the account will be closed and +the account will be marked as frozen. The download speed for all +objects associated with the account or payment account will be +downgraded. + +If someone deposits BNB tokens into a frozen payment account and the static balance is +enough for reserved fees, the account will be resumed automatically +(be noted, the deposit is payment deposit, not the general transfer). +Usually, the payment account will be "active" quickly. However, if there +are many outflows associated to the payment account, the payment account will be +queued for resume and handled in the following blocks. + ### Downgraded service Once the payment accounts run out of BNB, the objects associated with these payment accounts will