JakeHillion/storj
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/blueprints: update automatic account freezing/unfreezing blueprint

Browse Source 
This change updates the automatic account freezing/unfreezing blueprint
to account for new feedback and changes in the implementation process.

Change-Id: If1a478d961b67aa4a946793168a7f525e06bb9e7
This commit is contained in:
Jeremy Wharton 2022-12-06 10:13:46 -06:00
parent 91b551134d
commit d6bcde4672
1 changed files with 32 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/blueprints/automatic-account-freeze.md
View File

@ -6,29 +6,52 @@ This blueprint describes a way to allow user accounts to be automatically restri
## Background
Currently, there is no incentive for a user to ensure that the payment method attached to their account has a sufficient available balance to cover data usage charges. This results in the accrual of unpaid usage charges due to insufficient funds. The solution outlined in this document is as follows: When a user has not paid usage charges for a set period of time, their account’s usage limits will be set to zero, revoking their access to the Storj network. This process is known as freezing. The user is then given the opportunity to unfreeze their account by triggering collection of their outstanding invoice through the satellite UI.
Currently, there is no incentive for a user to ensure that the payment method attached to their account has a sufficient available balance to cover data usage charges. This results in the accrual of unpaid usage charges due to insufficient funds. The solution outlined in this document is as follows: when a user has not paid usage charges for a set period of time, they should not be able to upload or download data from the Storj network. This process is known as freezing. The user is then given the opportunity to unfreeze their account by triggering collection of their outstanding invoice. This can be done manually by clicking a button in the satellite UI or automatically when a payment method is added.
When the user attempts to use their account after it has been frozen, they will receive an error message notifying them of the account freeze and informing them of the steps they must take to restore their access.
The behavior described in this document only applies to paid-tier users despite the possibility of free-tier users' segment fees exceeding the amount discounted by a free-tier coupon. What actions we must take to address that issue is a different scope of work.
## Design
A new chore should be responsible for freezing the accounts of all paid-tier users who have not paid within a certain time period.
A new database table will be responsible for storing account freeze events. This table should contain event ID, user ID, and event type columns. There are 2 types of events, and there should be at most 1 event of each type for each user.
A new database column should track whether a user’s account is frozen. Usage limits are always treated as zero as long as the value of the column is true. This value should also be used to display a banner in the satellite UI notifying the user of the restrictions on their account if present.
* Warning: An event of this type is inserted when the user has been warned that their account is at risk of being frozen because of a low balance. If such an event exists for a user, they will not be sent any more warning emails. All warning events should be cleared at the beginning of the billing cycle so that new warning emails may be sent.
* Freeze: An event of this type is inserted to signify that the user is frozen. If there is no such event for a user, they should be considered unfrozen.
Once a user opts to unfreeze their account, payment of their outstanding invoice should be attempted. If it is successful, the user’s account should be automatically unfrozen.
A new chore will be responsible for freezing the accounts of all unfrozen paid-tier users who have not paid within a certain time period. The chore will also send 2 types of emails: an email to warn each user whose balance is nearly depleted about impending account restriction and an email to notify a user once their account has been restricted.
Frozen users will be displayed a satellite UI banner notifying them of the restrictions on their account and a button allowing them to unfreeze their account through invoice collection. Due to our caching of usage limits, recently unfrozen users will be displayed a message in the satellite UI stating that it will take up to 5 minutes for their restored usage limits to propagate to all servers in all regions.
## Rationale
It is possible to manually decrease a user’s usage limits after unsuccessful payment. However, doing so places an undue burden on service operators, especially as the number of accounts requiring such action increases. It is more efficient to automatically freeze accounts having unpaid usage charges, freeing operators to focus on other tasks.
It is possible to manually decrease a user’s usage limits after unsuccessful debt collection and increase them once payment has been resolved. However, doing so places an undue burden on satellite admins, especially as the number of accounts requiring such actions increases. It is more efficient to automatically freeze and unfreeze accounts, freeing satellite admins to focus on other tasks.
## Implementation
1. Create a new migration that adds a column to the users table specifying whether a user’s account is frozen.
2. Update the method(s) responsible for processing usage requests such that they reject any request originating from a frozen user regardless of what the user’s usage limits are.
3. Create a button on the billing page that, when clicked, attempts to collect payment on a frozen user’s outstanding invoice. If this attempt is successful, the user’s account is unfrozen; otherwise, the user’s account should remain frozen and an error message should be displayed notifying them of insufficient funding.
### Phase 1 - Automatic Account Unfreezing
In this phase, account freezes are manually performed by an administrator through the satellite admin UI. Because the existing usage limit verification functionality will be used, there will be no impact on existing metainfo validation.
1. Create a migration that adds a table containing account freeze events. In addition to the columns listed in the Design section of this document, the table should contain a temporary column for holding a user's usage limits at the time they were frozen. Once the user is unfrozen, their usage limits will be restored by referencing the information in this column.
2. Create a button on the billing page that, when clicked, attempts to collect payment on a frozen user’s outstanding invoice. If this attempt is successful, the user’s account is unfrozen by restoring their limits and deleting their freeze and warning events in the account freeze events table. Otherwise, the user’s account should remain frozen and an error message should be displayed notifying them of insufficient funding.
3. Update the payment method addition procedure such that when it is invoked by a frozen user, it attempts outstanding invoice collection using the newly-added payment method and unfreezes the user’s account if this process is successful.
4. Create a banner or modal notifying a user that their account is frozen.
5. Create a chore that iterates over all paid-tier users. Upon encountering one that has not paid within a specified grace period, that customer’s account is frozen and an e-mail is sent informing them of this.
5. Allow satellite admins to freeze accounts and retrieve accounts in need of freezing from within the satellite admin UI. Freezing involves creating a freeze event in the account freeze event table and zeroing a user’s usage limits.
### Phase 2 - Automatic Account Freezing
In this phase, a user’s usage limits are not touched when freezing or unfreezing. Instead, the account freeze table is used to determine the frozen state of a user’s account.
1. Update satellite accounting methods to utilize an account freeze cache in a manner similar to the existing usage limit cache. File operations should be rejected regardless of a user’s usage limits if the cached data states that the user is frozen.
2. Update the invoicing procedure such that it clears all warning events from the account freeze event table. This will allow warning emails to be sent in the new billing cycle.
3. Create a chore that performs the following operations:
1. It iterates over each open invoice whose usage period ended before the grace period, freezes the corresponding customer’s account, and sends them an email informing them of this.
2. It iterates over each unfrozen user whose balance does not cover their impending usage charges, and if there does not exist a warning event for them, it informs them that their account is at risk of being frozen if they cannot pay their dues in time. A warning event is then inserted into the account freeze events table.
4. Restore the usage limits zeroed from the first implementation phase.
5. Update the account freezing procedure such that it does not zero usage limits. This behavior is no longer required because usage limits are not read directly when rejecting file operations.
6. Drop the column containing saved usage limits from the account freeze event table.
7. Ensure that Uplink users with frozen accounts are informed of such when attempting to interact with the Storj network in a prohibited manner.
## Wrap Up