fedimint-dbtool 0.5.0

Tool to inspect Fedimint client and server databases
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# `dbtool`

**CAUTION: `dbtool` is a potentially destructive expert-tool, handle with care and if in doubt make a copy of your
database.**

For database layout see [`database.md`](../docs/database.md), but verify the information in the code before taking
potentially destructive action.

If your federation is running, a database lock should cause a panic when running these commands so be sure to stop
the federation first.

## Usage
```
$ fedimint-dbtool --help
Tool to inspect and manipulate rocksdb databases. All binary arguments (keys, values) have to be hex encoded

Usage: fedimint-dbtool <DATABASE> <COMMAND>

Commands:
  list    List all key-value pairs where the key begins with `prefix`
  write   Write a key-value pair to the database, overwriting the previous value if present
  delete  Delete a single entry from the database identified by `key`
  dump    Dump the database (or a subset) to the console as a json serialized string
  help    Print this message or the help of the given subcommand(s)

Arguments:
  <DATABASE>  - file path of the database

Options:
  -h, --help  Print help
```

## Deleting multiple elements

Other than the `list` command, the `delete` command only works on single keys. To delete entire key prefixes you can use
standard unix tools to build that functionality:

```bash
fedimint-dbtool <DATABASE> list <PREFIX> | cut -d ' ' -f 1 | xargs -n 1 -- fedimint-dbtool <DATABASE> delete
```

* `cut` selects a column from the space-separated output of `fedimint-dbtool`
  * `-d ' '` sets its delimiter to space
  * `-f 1` selects the first column
* `xargs` calls `fedimint-dbtool delete <key>` for each line of input
  * `-n 1` specifies that only one element will be passed to the specified command at a time

## Hex encoding

To en-/decode hex you can use `xxd`, although the raw binary data will not be of use that often.

```
$ echo -n "my binary data ..." | xxd -ps -c 0
6d792062696e6172792064617461202e2e2e

$ echo "6d792062696e6172792064617461202e2e2e" | xxd -r -p
my binary data ...

## Dump

The dump command can be used to dump a json-serialized portion of the database. Dump takes two required parameters <CFG_DIR> and <PASSWORD>. Password is used to decrypt the configuration file so the dbtool understand the type of module.
The dump command also takes optional parameters <MODULE> and <PREFIX> to dump only a subset of the database.

For more information on the modules and prefixes available to dump, see https://github.com/fedimint/fedimint/blob/master/docs/database.md. Table headers are modules and the Name column are prefixes.

Examples:
First, run a local federation in mprocs:
```shell
just mprocs
```

Dump the entire database of fedimintd-0
```shell
fedimint-dbtool $FM_DATA_DIR/fedimintd-0/database dump -- $FM_DATA_DIR/fedimintd-0 pass
```

Dump the consensus db entries of fedimintd-0
```shell
fedimint-dbtool $FM_DATA_DIR/fedimintd-0/database dump -- $FM_DATA_DIR/fedimintd-0 pass consensus
```

Dump the blocks from the wallet module of fedimintd-1
```shell
fedimint-dbtool $FM_DATA_DIR/fedimintd-1/database dump -- $FM_DATA_DIR/fedimintd-1 pass consensus blockhash
```

Dump the used notes from the mint module and the accepted transactions from consensus
```shell
fedimint-dbtool $FM_DATA_DIR/fedimintd-1/database dump -- $FM_DATA_DIR/fedimintd-1 pass consensus,mint notenonce,acceptedtransaction
```

Dump the entire client database (client password can be anything since it doesn't require decryption)
```shell
fedimint-dbtool $FM_CLIENT_DIR/client.db dump $FM_CLIENT_DIR clientpass client
```