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 Inputs and Outputs. 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 associated TXOIdentfier that identifies the TXO being consumed, and can be extended with ancillary information (e.g. Bitcoin's nSequence 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 a RecipientIdentifier and a Value type.
• A Transaction is a collection of Inputs to be consumed, and Outputs to be created. Its associated Digest type describes its transaction ID and must be produced by its associated HashWriter. 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 RecipientIdentifiers

• Address is a type that describes the network's address semantics. For Bitcoin this is an enum whose members wrap a String.
• AddressEncoder has associated Address and RecipientIdentifier types. It exposes encode_address, decode_address, and string_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.