# User 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