safekept/README.md

Multi-signature cryptocurrency wallet with time-lock faucet features for non-custodial responsible fund control

# SafeKept

A multi-signature wallet with time-lock features for responsible fund management. This wallet implements a 2-of-3 multi-signature setup with:

1. A user key that you control (always accessible)
2. A timelock key (used internally by the wallet for scheduled faucet withdrawals)
3. A backup key that becomes available only after the specified timelock period expires

## Purpose

SafeKept is specifically designed to help users maintain discipline with their cryptocurrency funds by making them harder to spend impulsively. It's useful for avoiding short-term impulsive spending, and may help in rehabilitation of some addictions, but is not a permanent or secure solution for resolving these issues. 

The time-lock feature ensures that funds can't be accessed immediately, while still providing eventual access when needed without requiring third party access or keeping of potentially critical funds. 

Thus, Safekept lets the user:
- Feel safe from exploitation through fees or theft
- Have peace of mind of their funds and coins
- Feel safe from themselves, temporarily

While this wallet should not be used in place of more robust security systems for critical funds or savings, it is an effective solution for momentary lapses in judgement.


## Features

- **Non-custodial** - Your keys, just delayed a bit. All functions result in your ownership of the keys, and before that, they're owned by no one. 
- **Open-source** - The software is completely open source, letting anyone inspect and ensure nothing malicious is happening between the lines. 
- **BTC/LTC Multisig** - Effective multisignature wallets, not TRX. This is a real wallet, and can be used independently of the faucet/safety features
- **Faucet function** - Set based on a server time (for more accountability, but less self-containedness) or local (for less, but greater security)
- **CLI or UI** - Can be easily controlled through the command line, or via user interface in the command line window
- **Whitelisting + Tamper-protection** - Permit sending only to certain addresses, and password-protect the wallet's self-destruct function to ensure it's only used by the right user, at the right time
- **Integrity checked** - If files are edited or tampered with, the wallet won't function, and if this is unfixable, the user must wait until the full duration is complete to retrieve the backup key. 

## Installation

```bash
# Install globally from npm
npm install -g safekept

# Or install from the repository
git clone https://github.com/rubyatmidnight/safekept.git
cd safekept
npm install
npm link
```

## Usage

### Interactive UI

The easiest way to use SafeKept is through the interactive terminal UI:

```bash
safekept ui
```

This will launch a menu-based interface with all available options.

### Desktop App (Experimental)

A basic desktop application is also available, but is still in early development:

```bash
# First install the optional Electron dependencies
npm install --save-optional electron electron-packager

# Then run the desktop app
npm run electron
```

### Command Line Interface

Alternatively or to automate features, you can use the command line interface:

```bash
# Setting up a new wallet
safekept setup --coin litecoin

# Getting deposit address
safekept deposit

# Using the faucet for a withdrawal
safekept faucet --to ltc_address

# Checking wallet info and status
safekept info

# Checking balance
safekept balance

# Verifying system integrity
safekept verify

# Withdrawing funds
safekept withdraw --amount 0.5 --to ltc_address

# Clearing wallet data (USE WITH CAUTION)
safekept clear-wallet
```

## Whitelist Management

The whitelist feature allows you to restrict withdrawals to specific addresses:

```bash
# View current whitelist
safekept whitelist

# Enable whitelist
safekept whitelist-enable

# Add addresses to whitelist
safekept whitelist-add --addresses "addr1,addr2,addr3"

# Remove addresses from whitelist
safekept whitelist-remove --addresses "addr1"

# Disable whitelist
safekept whitelist-disable
```

## Faucet Feature

The faucet allows you to set up controlled periodic withdrawals:

1. Set a percentage (e.g., 10%) of your total deposit that can be withdrawn at once
2. Set a time interval between withdrawals (e.g., 24 hours or as little as a few minutes)
3. The system will only allow withdrawals of that fixed percentage at the specified intervals
4. Uses the timelock key internally, no need to wait for the backup key to be available
5. Follows the schedule and enforces the waiting period between withdrawals


## Security Considerations

- **Private keys** are stored locally on your computer.
- The time-lock is enforced by the software, not the blockchain. Potential blockchian 
- Consider using a hardware wallet for the user key in production
- Protect access to the wallet 


## Backup and Recovery

The backup key is a safety mechanism that becomes available only after the timelock period expires. To check if your backup key is available:

```bash
safekept backup-key
```

This will show the backup key if the timelock has expired or tell you how long you need to wait.

You should write down and safely store:

1. Your user private key (shown during setup)
2. The wallet address
3. The unlock date for the backup key (when it will become available)

Once the backup key becomes available, you can use it with your user key to recover funds in case of emergency.

## License

MIT