# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bitsave.io/docs/user-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.