12 releases (6 breaking)
0.12.0 | Jul 27, 2024 |
---|---|
0.11.1 | Jun 9, 2024 |
0.8.7 | Aug 23, 2023 |
0.8.3 | Mar 15, 2023 |
0.2.2 | Apr 4, 2021 |
#13 in #cryptocurrency
188,938 downloads per month
Used in 308 crates
(6 directly)
39KB
726 lines
Coins Core
coins-core
is an abstract description of UTXO transactions. It provides a
collection of traits that provide consistent interfaces to UTXO transaction
construction. Coins's traits ensure that types are consistent across all
steps in the tx construction process, and allow for code reuse when building
transactions on multiple chains (e.g. Bitcoin Mainnet and Bitcoin Testnet).
Many concepts familiar to UTXO chain developers have been genericized.
Transactions are modeled as a collection of Input
s and Output
s. Rather than
addresses or scripts, the Output
trait has an associated
RecipientIdentifier
. Similarly, rather than an outpoint, the Input
trait
has an associated TXOIdentfier
.
Support for other chains may be added by implementing these traits, and
extending the implementations with network-specific functionality. We have
provided an implementation suitable for Bitcoin chains (mainnet, testnet, and
signet) in the bitcoins
crate.
Type Layout
Ser trait
The Ser
trait is a simple serialization API using std::io::{Read, Write}
.
Implementers define the binary serialization format of the type, as well as the
JSON serialization. The transaction type must implement Ser
, as the provided
txid
logic assumes access to the serialize
method.
Ser
has an associated Error
type. Most basic types can simply use the
provided SerError
. However, more complex (de)serialization will want to
implement a custom error type to handle (e.g.) invalid transactions. These
types must be easily instantiated from a SerError
or an std::io::Error
.
Transaction types
These describe the components of a transaction.
- A
TXOIdentfier
uniquely identifies a transaction output. In Bitcoin, this is an outpoint. - An
Input
describes the input to a transaction. It has an associatedTXOIdentfier
that identifies the TXO being consumed, and can be extended with ancillary information (e.g. Bitcoin'snSequence
field). - A
RecipientIdentifier
identifies the recipient of a new TXO. In Bitcoin, these are pubkey scripts. - An
Output
describes the output to a transaction. It has an associated aRecipientIdentifier
and aValue
type. - A
Transaction
is a collection ofInput
s to be consumed, andOutput
s to be created. Its associatedDigest
type describes its transaction ID and must be produced by its associatedHashWriter
. This allows transactions to specify the digest algorithm used to generate their sighash digest and their TXID.
Encoder types
The encoder translates between human-facing data and protocol-facing data.
Particularly between addresses and RecipientIdentifier
s
Address
is a type that describes the network's address semantics. For Bitcoin this is an enum whose members wrap aString
.AddressEncoder
has associatedAddress
andRecipientIdentifier
types. It exposesencode_address
,decode_address
, andstring_to_address
it order to enable conversion between them.
Builder type
The transaction builder provides a convenient interface for constructing
Transaction
objects. It has associated Transaction
and AddressEncoder
types, and ensures that they use the same RecipientIdentifier
. This allows us
to provide a simple pay(value, address)
interface on the builder.
Network type
The network type guarantees type consistency across a set of implementing
types, provides a unified interface to accessing them. This is intended to be
the primary entry point for the implementing libraries. It guarantees that the
Builder
, AddressEncoder
, and Transaction
types use the same Error
, the
same RecipientIdentifier
, the same TXOIdentfier
, and the same Address
type. It provides passthroughs to the AddressEncoder
's associated functions,
and a convenience method for instantiating a new builder.
Dependencies
~2.1–2.8MB
~43K SLoC