# walleth

A (WIP) Rust library for easily create, manage, use and protect Ethereum accounts. Interacting with keys and signing transactions securely (will be) made as easy as breathing.

## Table of contents

- [Modules](#modules)
  - [Keychain](#keychain)
  - [Vault](#vault)
  - [Safe](#safe)

## Modules

### Keychain

The `Keychain` is the main data structure to easily manage your wallet's keys. It provides access to an HD Wallet generated by a mnemonic (provided on construction or created on the fly).

It's core purpose is to provide an easy to use API to create, manage, use and protect identities, or public-private keypairs.

The underlying sensitive data that the `Keychain` holds can be locked with a password. The provided password and a random salt are used to derive a public key, that is used to encrypt all the internal `Vault` in a `Safe` component.

More information on the `Vault` and on the `Safe` can be found in the [Vault](#vault) and [Safe](#safe) component sections.

```rust
use walleth::Keychain

// Let's create a Keychain, a simple identity manager
let keychain = Keychain::new();

// And then add an ethereum address in a single line!
// The `account` variable is an instance of a struct
// that contains some non-sensitive data (no private keys!)
let account = keychain.add_account().unwrap();

// Let's execute something whenever the keychain state
// changes
keychain.subscribe(|state| {
  println!("Keychain state changed: {:?}", state);
});

// And then lock it!
keychain.lock("my crazy password");

// You forgot to sign something?
// unlock again..
keychain.unlock("my crazy password");

// ..and use a signer!
let signature = keychain.use_signer(account.address, |signer| {
  Ok(signer.sign(&b"A message")?)
}).unwrap();
```

### Vault

A `Vault` is a safe wrapper around a Hierarchical Deterministic (HD) wallet
backed by a mnemonic phrase. It can generate new keys and sign transactions.

When locked, the mnemonic phrase is encrypted safely and the keys are removed from memory.
When unlocked, the mnemonic phrase is decrypted and the keys are recreated in memory.

If you took a look at the [`Keychain`](#keychain), the `Vault`'s API may look familiar:

```rust
use walleth::Vault;

// Create a new vault
let vault = Vault::new();

// Generate new private key from the HD wallet in the vault
vault.add_key();
vault.add_key();

// Lock the vault
vault.lock(b"my secret password");

// Unlock the vault
vault.unlock(b"my secret password");

// Use a signer from the vault
vault.use_signer(0, |signer| {
 signer.sign(&[0; 32])
});
```

### Safe

A Safe is a purpose-agnostic container for encrypted data, 
which provides an handy function to create it from a key, some unencrypted bytes
and some arbitrary metadata. 

The metadata is not encrypted and can be used to
store information about the encrypted data.

The unencrypted bytes slice passed on construction is encrypted and can be used
to store sensitive information.

```rust
use walleth::Safe;

let safe = Safe::new("metadata", &[0, 1, 2, 3]);

assert_eq!(safe.metadata, "metadata");
assert_eq!(safe.get_bytes(), &[0, 1, 2, 3]);

let safe = Safe::from_plain_bytes("metadata", &[0, 32], &[0, 1, 2, 3, 4]).unwrap();

assert_eq!(safe.metadata, "metadata");
assert_eq!(safe.get_bytes(), &[0, 1, 2, 3]);
```

### HDWallet

A simple module to create a Hierarchically deterministic wallet.

```rust
use walleth::HDWallet;

// Create a new wallet from random seed
let hdwallet = HDWallet::new();

// Or from a mnemonic
let hdwallet = HDWallet::::from_mnemonic_str("grocery belt target explain clay essay focus spatial skull brain measure matrix toward visual protect owner stone scale slim ghost panda exact combine game").unwrap();

// Derive private key at path m'/60'/0'/0'/0
let private_key = hdwallet.private_key_at_path(0, 0, 0);
```