User Flow

This chapter describes the actions users can perform in BitSave protocol and explains how each operation affects a user’s savings and the protocol’s execution flow.

Registration with the Protocol

Before creating any savings, a user must register with BitSave.

Steps

1. Call the BitSave parent contract

   The user initiates interaction with the Bitsave contract.

2. Child Contract Deployment Upon successful registration, the protocol deploys a unique ChildBitsave contract for the user and permanently maps it to their address.

Outputs

• A dedicated ChildBitsave contract is created for the user

• The user is now able to create and manage savings

• A one-time registration fee of $1 is deducted in native ETH

Creating a Savings Plan

Creating a savings plan initialises a time-locked savings position inside the user’s child contract.

Steps

1. Approve ERC-20 Token For ERC-20 savings, the user approves the BitSave parent contract to transfer the specified token amount.

2. Create Savings via Parent Contract The user initiates savings creation through the Bitsave contract, specifying:

   • Savings amount

   • Maturity time

   • Early withdrawal penalty parameters

3. Savings Creation Fee

   As part of the savings creation transaction, a protocol-defined savings fee of $1 is deducted in native ETH by the parent contract.

4. Fund Routing Funds are transferred to the parent contract and immediately forwarded to the user’s ChildBitsave contract within the same operation.

5. Savings Record Creation The child contract records the savings metadata, including principal, maturity time, penalty rules, and tracking points.

Outputs

• A new savings plan is created

• A savings creation fee is collected

• Funds are held in the user’s child contract

• Savings become time-locked until maturity (unless withdrawn early)

Incrementing an Existing Savings

Users can add more funds to an existing savings plan.

Steps

1. Approve Additional Tokens The user approves the parent contract to transfer additional ERC-20 tokens.

2. Call Savings Increment Function The increment request is routed through the parent contract.

3. Funds Are Forwarded to Child Contract The parent contract immediately forwards funds to the user’s child contract.

4. Savings Metadata Is Updated The child contract updates the principal and associated tracking data.

Outputs

• Savings principal increases

• Existing maturity and penalty rules remain in effect

• Funds remain isolated within the user’s child contract

Withdrawing Funds

Users can withdraw funds from a savings plan either at maturity or before maturity.

To withdraw a savings plan, the user specifies the name of the savings, which uniquely identifies the savings position within the user’s child contract.

Withdrawal Rules

• At or after maturity: The full principal amount is returned to the user.

• Before maturity: A penalty is applied to the principal, according to the savings configuration.

Steps

1. Initiate Withdrawal The user requests withdrawal through the BitSave frontend or via contract interaction.

2. Savings State Check The child contract checks the savings maturity time and penalty conditions.

3. Penalty Application (if applicable) If withdrawn early, the configured penalty is applied.

4. Fund Transfer to User The child contract transfers the resulting amount back to the user.

Outputs

• Savings plan is reduced or closed

• Funds are returned directly from the child contract

• No pooled funds or shared balances are involved

Withdrawing Funds Without the Frontend (Manual / Emergency)

This method allows users to withdraw their savings directly through a block explorer, for example, if the BitSave frontend is unavailable.

⚠️ This flow is intended for advanced users.

Steps

1. Connect your wallet Open the BitSave parent contract on a block explorer ( and connect your wallet.

2. Navigate to “Write Contract”

3. Call withdrawSavings

4. Enter Savings Name Type the name of your savings and add a trailing space ( ).

5. Approve the Transaction

Once confirmed, the savings is withdrawn according to protocol rules.

Outputs

• Funds are withdrawn directly from the user’s child contract

• Early withdrawal penalties apply if the savings has not matured

• No frontend interaction is required