1 /*Package walletdb provides a namespaced database interface for btcwallet.
2 3 Overview
4 5 A wallet essentially consists of a multitude of stored data such as private and public keys, key derivation bits,
6 pay-to-script-hash scripts, and various metadata. One of the issues with many wallets is they are tightly integrated.
7 Designing a wallet with loosely coupled components that provide specific functionality is ideal, however it presents a
8 challenge in regards to data storage since each component needs to store its own data without knowing the internals of
9 other components or breaking atomicity.
10 11 This package solves this issue by providing a pluggable driver, namespaced database interface that is intended to be
12 used by the main wallet daemon. This allows the potential for any backend database type with a suitable driver. Each
13 component, which will typically be a package, can then implement various functionality such as address management,
14 voting pools, and colored coin metadata in their own namespace without having to worry about conflicts with other
15 packages even though they are sharing the same database that is managed by the wallet.
16 17 A quick overview of the features walletdb provides are as follows:
18 19 - Key/value store
20 21 - Namespace support
22 23 - Allows multiple packages to have their own area in the database without
24 worrying about conflicts
25 26 - Read-only and read-write transactions with both manual and managed modes
27 28 - Nested buckets
29 30 - Supports registration of backend databases
31 32 - Comprehensive test coverage
33 34 Database
35 36 The main entry point is the DB interface. It exposes functionality for creating, retrieving, and removing namespaces. It
37 is obtained via the Create and Open functions which take a database type string that identifies the specific database
38 driver (backend) to use as well as arguments specific to the specified driver.
39 40 Namespaces
41 42 The Namespace interface is an abstraction that provides facilities for obtaining transactions (the Tx interface) that
43 are the basis of all database reads and writes. Unlike some database interfaces that support reading and writing without
44 transactions, this interface requires transactions even when only reading or writing a single key.
45 46 The Begin function provides an unmanaged transaction while the View and Update functions provide a managed transaction.
47 These are described in more detail below.
48 49 Transactions
50 51 The Tx interface provides facilities for rolling back or commiting changes that took place while the transaction was
52 active. It also provides the root bucket under which all keys, values, and nested buckets are stored. A transaction can
53 either be read-only or read-write and managed or unmanaged.
54 55 Managed versus Unmanaged Transactions
56 57 A managed transaction is one where the caller provides a function to execute within the context of the transaction and
58 the commit or rollback is handled automatically depending on whether or not the provided function returns an error.
59 Attempting to manually call Rollback or Commit on the managed transaction will result in a panic.
60 61 An unmanaged transaction, on the other hand, requires the caller to manually call Commit or Rollback when they are
62 finished with it. Leaving transactions open for long periods of time can have several adverse effects, so it is
63 recommended that managed transactions are used instead.
64 65 Buckets
66 67 The Bucket interface provides the ability to manipulate key/value pairs and nested buckets as well as iterate through
68 them.
69 70 The Get, Put, and Delete functions work with key/value pairs, while the Bucket, CreateBucket, CreateBucketIfNotExists,
71 and DeleteBucket functions work with buckets. The ForEach function allows the caller to provide a function to be called
72 with each key/value pair and nested bucket in the current bucket.
73 74 Root Bucket
75 76 As discussed above, all of the functions which are used to manipulate key/value pairs and nested buckets exist on the
77 Bucket interface. The root bucket is the upper-most bucket in a namespace under which data is stored and is created at
78 the same time as the namespace. Use the RootBucket function on the Tx interface to retrieve it.
79 80 Nested Buckets
81 82 The CreateBucket and CreateBucketIfNotExists functions on the Bucket interface provide the ability to create an
83 arbitrary number of nested buckets. It is a good idea to avoid a lot of buckets with little data in them as it could
84 lead to poor page utilization depending on the specific driver in use.
85 */
86 package walletdb
87