/
interfaces.go
130 lines (104 loc) · 4.67 KB
/
interfaces.go
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
// This Source Code Form is subject to the terms of the MIT License.
// If a copy of the MIT License was not distributed with this
// file, you can obtain one at https://opensource.org/licenses/MIT.
//
// Copyright (c) DUSK NETWORK. All rights reserved.
package database
import (
"errors"
"math"
"github.com/dusk-network/dusk-blockchain/pkg/core/data/block"
"github.com/dusk-network/dusk-blockchain/pkg/core/data/ipc/transactions"
)
var (
// Common blockchain database errors. See also database/testing for the
// cases where they are returned.
// ErrTxNotFound returned on a tx lookup by hash.
ErrTxNotFound = errors.New("database: transaction not found")
// ErrBlockNotFound returned on a block lookup by hash or height.
ErrBlockNotFound = errors.New("database: block not found")
// ErrStateNotFound returned on missing state db entry.
ErrStateNotFound = errors.New("database: state not found")
// ErrOutputNotFound returned on output lookup during tx verification.
ErrOutputNotFound = errors.New("database: output not found")
// ErrStateHashNotFound returned on state hash not linked to any block.
ErrStateHashNotFound = errors.New("database: state hash was not found")
// AnyTxType is used as a filter value on FetchBlockTxByHash.
AnyTxType = transactions.TxType(math.MaxUint8)
)
// A Driver represents an application programming interface for accessing
// blockchain database management systems.
//
// It is conceptually similar to ODBC for DBMS.
type Driver interface {
// Open returns a new connection to a blockchain database. The path is a
// string in a driver-specific format.
Open(path string, readonly bool) (DB, error)
// Close terminates all DB connections and closes underlying storage.
Close() error
// Name returns a unique identifier that can be used to register the driver.
Name() string
}
// Transaction represents transaction layer. Transaction should provide basic
// transactions to fetch and store blockchain data.
//
// To simplify code reading with database pkg we should use 'Tx' to refer to
// blockchain transaction and 'Transaction' to refer to database transaction.
type Transaction interface {
// Read-only transactions.
FetchBlockHeader(hash []byte) (*block.Header, error)
// Fetch all of the Txs that belong to a block with this header.hash.
FetchBlockTxs(hash []byte) ([]transactions.ContractCall, error)
// Fetch tx by txID. If succeeds, it returns tx data, tx index and
// hash of the block it belongs to.
FetchBlockTxByHash(txID []byte) (tx transactions.ContractCall, txIndex uint32, blockHeaderHash []byte, err error)
FetchBlockHashByHeight(height uint64) ([]byte, error)
FetchBlockExists(hash []byte) (bool, error)
FetchBlockByStateRoot(fromHeight uint64, stateRoot []byte) (*block.Block, error)
// Fetch chain registry (chain tip hash, persisted block etc).
FetchRegistry() (*Registry, error)
// Read-write transactions
// Store the next chain block in a append-only manner
// Overwrites only if block with same hash already stored
// Not to be called concurrently, as it updates chain tip.
StoreBlock(block *block.Block, persisted bool) error
// DeleteBlock deletes all records associated with a specified block.
DeleteBlock(b *block.Block) error
// FetchBlock will return a block, given a hash.
FetchBlock(hash []byte) (*block.Block, error)
// FetchCurrentHeight returns the height of the most recently stored
// block in the database.
FetchCurrentHeight() (uint64, error)
// FetchBlockHeightSince try to find height of a block generated around
// sinceUnixTime starting the search from height (tip - offset).
FetchBlockHeightSince(sinceUnixTime int64, offset uint64) (uint64, error)
// StoreCandidateMessage will...
StoreCandidateMessage(cm block.Block) error
FetchCandidateMessage(hash []byte) (block.Block, error)
ClearCandidateMessages() error
// ClearDatabase will remove all information from the database.
ClearDatabase() error
// Atomic storage.
Commit() error
Rollback() error
Close()
}
// DB is a thin layer on top of Transaction providing a manageable execution.
type DB interface {
// View provides a managed execution of a read-only transaction.
View(fn func(t Transaction) error) error
// Update provides a managed execution of a read-write atomic transaction.
//
// An atomic transaction is an indivisible and irreducible series of
// database operations such that either all occur, or nothing occurs.
//
// Transaction commit will happen only if no error is returned by `fn`
// and no panic is raised on `fn` execution.
Update(fn func(t Transaction) error) error
Close() error
}
// Registry represents a set database records that provide chain metadata.
type Registry struct {
TipHash []byte
PersistedHash []byte
}