coin

README

Coin

This is a basic cryptocurrency library, made for fun. It has no networking capabilities. It has no consensus mechanism. It has no CLI.

How it works

Account

A public and private key. The public key is used as the "address" of the account. The private key is used to sign transactions to prove that they came from the account. Anyone with the private key has access to the account.

Transaction

An object containing the public key of the sender account, the public key of the receiver account, the amount of coin to be sent, and the signature from the sender account. The data signed in a transaction includes the signature of the previous transaction. This is used by the ledger or bank to chain transactions together.

A special case is a genesis transaction. In this type of transaction, the public key of the sender account and receiver account are the same. The sending account grants itself an amount of coin. This is the first transaction in a ledger or bank.

Ledger

A list of transactions. A genesis transaction is first before all other transactions and there is only one. Transactions are verified when they are added.

Bank

A store of balances. Unlike the ledger, this does not store transaction information. All it does is store balances and the current signature.

Installation

Run go get -u github.com/patrickmcnamara/coin.

License

This project is licensed under the GNU Lesser General Public License v3.0.

Documentation

Index

• Variables
• type Account
  • func NewAccount() (acc Account)
  • func NewAccountFromSeed(seed []byte) (acc Account, err error)
  • func (acc Account) NewGenesisTransaction(amount uint32) (trn Transaction)
  • func (acc Account) NewTransaction(pubKey PublicKey, amount uint32, currSig Signature) (trn Transaction)
  • func (acc Account) Sign(data []byte) (sig Signature)
  • func (acc Account) Verify(data []byte, sig Signature) bool
• type Bank
  • func NewBank(trn Transaction) (bnk *Bank, err error)
  • func (bnk *Bank) Balance(pubKey PublicKey) uint32
  • func (bnk *Bank) Signature() Signature
  • func (bnk *Bank) Transaction(trn Transaction) error
• type Ledger
  • func NewLedger() *Ledger
  • func (led *Ledger) AddGenesisTransaction(trn Transaction) error
  • func (led *Ledger) AddTransaction(trn Transaction) error
  • func (led *Ledger) BalanceOf(pubKey PublicKey) uint32
  • func (led *Ledger) Balances() map[PublicKey]uint32
  • func (led *Ledger) Do(f func(trn Transaction) error) error
  • func (led *Ledger) GenesisTransaction() (trn Transaction, err error)
  • func (led *Ledger) LatestTransaction() (trn Transaction, err error)
  • func (led *Ledger) Signature() Signature
  • func (led *Ledger) Size() uint64
  • func (led *Ledger) Transactions() []Transaction
  • func (led *Ledger) TransactionsOf(pubkey PublicKey) []Transaction
• type PrivateKey
• type PublicKey
• type Signature
• type Transaction
  • func (trn Transaction) Contract(currSig Signature) []byte
  • func (trn Transaction) Sign(prvKey PrivateKey, currSig Signature) (sig Signature)
  • func (trn Transaction) Verify(currSig Signature) bool

Variables

var (
	ErrTrnAmountZero    = errors.New("amount cannot be zero")
	ErrTrnAmountBalance = errors.New("sender balance too low")
	ErrTrnSameReceiver  = errors.New("receiver cannot be same as sender")
	ErrTrnBadSignature  = errors.New("signature invalid")
)

Transaction errors

These indicate why a transaction was invalid.

var (
	ErrLedAlreadyGenesis = errors.New("genesis transaction already in ledger")
	ErrLedNoGenesis      = errors.New("no genesis transaction in ledger")
)

Ledger errors

These indicate why a transaction could not be added to the ledger.

var (
	ErrAccShortSeed = errors.New("seed must have a length of at least 32")
)

Account errors

These indicate why an account could not be generated.

Types

type Account

type Account struct {
	PublicKey  PublicKey  `json:"publicKey"`
	PrivateKey PrivateKey `json:"privateKey"`
}

Account is a coin account. It can make transactions on a ledger. It has a public key, which is used as the address of the account, and private key, which is used to sign transactions. Anyone with access to the private key will have access to the account.

func NewAccount

func NewAccount() (acc Account)

NewAccount returns a new account with a new public and private key.

func NewAccountFromSeed

func NewAccountFromSeed(seed []byte) (acc Account, err error)

NewAccountFromSeed returns a new account with a public and private key generated from a given seed.

func (Account) NewGenesisTransaction

func (acc Account) NewGenesisTransaction(amount uint32) (trn Transaction)

NewGenesisTransaction creates a new transaction where the account grants itself an amount of coin. This must be the first transaction in a ledger or bank and will be invalid otherwise.

func (Account) NewTransaction

func (acc Account) NewTransaction(pubKey PublicKey, amount uint32, currSig Signature) (trn Transaction)

NewTransaction creates a new transaction where an account send an amount of coin to another account, addressed by their respective public keys. It is signed by the private key of the sender. The signature of the ledger or bank that the transaction is to be added to is also required.

func (Account) Sign

func (acc Account) Sign(data []byte) (sig Signature)

Sign signs data with the private key of the account.

func (Account) Verify

func (acc Account) Verify(data []byte, sig Signature) bool

Verify verifies signed data with the public key of the account.

type Bank

type Bank struct {
	// contains filtered or unexported fields
}

Bank is a store of balances. It processes transactions but doesn't keep a transaction history.

func NewBank

func NewBank(trn Transaction) (bnk *Bank, err error)

NewBank creates a new bank given a genesis transaction.

func (*Bank) Balance

func (bnk *Bank) Balance(pubKey PublicKey) uint32

Balance returns the balance of an account in this bank given its public key. If the public key has never been used, it returns 0.

func (*Bank) Signature

func (bnk *Bank) Signature() Signature

Signature returns the current signature of the bank. This is the signature of the latest transaction.

func (*Bank) Transaction

func (bnk *Bank) Transaction(trn Transaction) error

Transaction validates and processes the given transaction in the bank. It updates the balances of the accounts and the bank's current signature.

type Ledger

type Ledger struct {
	// contains filtered or unexported fields
}

Ledger is a list of transactions.

func NewLedger

func NewLedger() *Ledger

NewLedger returns a new, empty ledger.

func (*Ledger) AddGenesisTransaction

func (led *Ledger) AddGenesisTransaction(trn Transaction) error

AddGenesisTransaction adds a genesis transaction to the ledger. Only a genesis transaction is valid as the first transaction of the ledger.

func (*Ledger) AddTransaction

func (led *Ledger) AddTransaction(trn Transaction) error

AddTransaction verifies that a transaction is valid and adds it to the ledger if it is.

func (*Ledger) BalanceOf

func (led *Ledger) BalanceOf(pubKey PublicKey) uint32

BalanceOf returns the balance of an account in the ledger given its public key. If the account is not in the ledger, it will return 0.

func (*Ledger) Balances

func (led *Ledger) Balances() map[PublicKey]uint32

Balances returns a map of every public key in the ledger and the balances of the accounts associated with those public keys.

func (*Ledger) Do

func (led *Ledger) Do(f func(trn Transaction) error) error

Do calls the given function on each transaction in the ledger, in order. If any of the calls return an error, Do will return that error immediately.

func (*Ledger) GenesisTransaction

func (led *Ledger) GenesisTransaction() (trn Transaction, err error)

GenesisTransaction returns the first transaction of the ledger.

func (*Ledger) LatestTransaction

func (led *Ledger) LatestTransaction() (trn Transaction, err error)

LatestTransaction returns the latest transaction of the ledger.

func (*Ledger) Signature

func (led *Ledger) Signature() Signature

Signature returns the current signature of the ledger. This is the signature of the latest transaction.

func (*Ledger) Size

func (led *Ledger) Size() uint64

Size returns the number of transactions in the ledger.

func (*Ledger) Transactions

func (led *Ledger) Transactions() []Transaction

Transactions returns all transactions in the ledger.

func (*Ledger) TransactionsOf

func (led *Ledger) TransactionsOf(pubkey PublicKey) []Transaction

TransactionsOf will return a slice of transactions in the ledger involving an account given its public key.

type PrivateKey

type PrivateKey [ed25519.PrivateKeySize]byte

PrivateKey is a private key of an account.

type PublicKey

type PublicKey [ed25519.PublicKeySize]byte

PublicKey is a public key and address of an account.

var BurnAddress PublicKey

BurnAddress is a public key of an account that is inaccessible.

type Signature

type Signature [ed25519.SignatureSize]byte

Signature is a signature signed with the private key of an account.

type Transaction

type Transaction struct {
	From      PublicKey `json:"from"`
	To        PublicKey `json:"to"`
	Amount    uint32    `json:"amount"`
	Signature Signature `json:"signature"`
}

Transaction is a coin transaction. An amount of coin is sent from one account to another. The sending account signs the transaction with its private key.

func (Transaction) Contract

func (trn Transaction) Contract(currSig Signature) []byte

Contract returns the bytes that account signs to create a transaction with the private key.

func (Transaction) Sign

func (trn Transaction) Sign(prvKey PrivateKey, currSig Signature) (sig Signature)

Sign returns the signature of a transaction given the private key of the sender and the signature of the ledger or bank.

func (Transaction) Verify

func (trn Transaction) Verify(currSig Signature) bool

Verify verifies the signature of the transaction with the public key of the sender and the signature of the ledger or bank.