spec

package module
v0.0.0-...-5ea2479 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2018 License: GPL-3.0 Imports: 4 Imported by: 6

README

go-spec

The interface specifications for the blocktop blockchain development kit components.

Overview

This repository contains the interfaces that components must implement in order to participate in a blocktop-based project. One can see the relationships between these components by examining tbe interfaces.

Interfaces

Controller

A Controller manages Blockchains and the flow of Blocks and Transactions into them.

Blockchain

A Blockchain employs a BlockGenerator to create new Blocks locally. It runs a Consensus component that tells it which head Block on which the next Block should be generated. It also receives newly committed Blocks from Consensus and passes them to the BlockGenerator for computation and storage.

Consensus

A Consensus component tracks incoming Blocks, whether generated locally or received from another NetworkNode. When Blocks that have the same parent Block arrive, It uses a BlockComparator function to determine the Block that is to remain in competition. Consensus confirms Blocks and passes them to Blockchain for further processing.

BlockGenerator

A BlockGenerator is responsible for the generation of new Blocks, including attaching transactions to them. It may use any algorithm required for the syatem being implemented, including hash generation (Proof-of-Work), coin staking (Proof-of-Stake), or others. A BlockGenerator also maintains a collection of TransactionHandlers. A BlockGenerator is responsible for validating Blocks and committing them to storage.

TransactionHandler

A TransactionHandler validates and executes Transactions.

Block

A Block is the unit member of a Blockchain. It has a pointer to its parent and holds a collection of Transactions. A Block conforms to the Marshalled interface which allows it to be serialized and deserialized for network communication.

Transaction

A Transaction is an instruction and holds a set of parameters that a TransactionHandler uses to compute the intended update to the state of the system.

Documentation

Index

Constants

View Source 
const (
	ResourceTypeBlock       string = "block"
	ResourceTypeTransaction string = "transaction"
)

Variables

This section is empty.

Functions

func FullyQualifiedName 

func FullyQualifiedName(item Marshalled) string

Types

type Account 

type Account interface {
	Address() string
	Marshal() proto.Message
}

type AddBlocksResponse 

type AddBlocksResponse struct {
	AddedBlock         Block
	AddedToRoot        int
	MaxBlockNumber     uint64
	DisqualifiedBlocks []Block
	Error              error
}

type Block 

type Block interface {
	Marshalled

	// returns the identifier of the block's parent
	ParentHash() string

	// returns the sequential number of the block in the blockchain
	BlockNumber() uint64

	// validates the block
	Valid() bool

	// gets the block's transactions
	Transactions() []Transaction

	// gets the Unix time in milliseconds the block was generated
	Timestamp() int64
}

Block interface specifies getters required for `blocktop` to function. Custom blocks must implement this interface.

type BlockComparator 

type BlockComparator func([]Block) Block

type BlockConfirmationHandler 

type BlockConfirmationHandler func(Block)

type BlockGenerator 

type BlockGenerator interface {
	Type() string
	ReceiveTransaction(*NetworkMessage) (Transaction, error)
	TryCommitBlock(newBlock Block, branch []Block) bool
	CommitBlock(Block)
	GenerateGenesisBlock() Block
	GenerateBlock(parentBranch []Block) (newBlock Block)
	BlockPrototype() Block
}

type Blockchain 

type Blockchain interface {
	Name() string
	Consensus() Consensus
	Start(ctx context.Context)
	Stop()
	IsRunning() bool
	GenerateBlock(branch []Block, rootID int) Block
	GenerateGenesis() Block
	AddBlocks(blocks []Block, local bool) *AddBlocksResponse
	ReceiveTransaction(*NetworkMessage) error
}

type CompetingBranch 

type CompetingBranch interface {
	// Blocks returns the blocks contained in the branch, ordered from
	// head to confirming root.
	Blocks() []Block

	// RootID is the identifier of the branch.
	RootID() int

	// ConsecutiveLocalHits returns the number of times the branch has
	// received blocks for evaluation from only the local node. This
	// is an indicator that the current node is operating in an echo
	// chamber.
	ConsecutiveLocalHits() int

	// HitRate is a measure of popularity of the branch. If returns the
	// number of blocks per second that are being evaluated from the
	// network and locally for addition to the branch.
	HitRate() float64
}

type Competition 

type Competition interface {
	// Branches returns the current competing branches being tracked
	// in the consensus system indexed by RootID.
	Branches() map[int]CompetingBranch
}

Competition represents the latest block competition information. This entity is shared between Consensus and Blockchain.

type Consensus 

type Consensus interface {
	OnBlockConfirmed(BlockConfirmationHandler)
	OnLocalBlockConfirmed(BlockConfirmationHandler)
	Evaluate() Competition
	AddBlocks(block []Block, local bool) *AddBlocksResponse
	ConfirmBlocks()
	WasSeen(block Block) bool
	SetCompeted(head Block)
	SetConfirmingRoot(rootID int)
}

type Controller 

type Controller interface {
	Start(context.Context)
	StartBlockchain(ctx context.Context, blockchainType string)
	StopBlockchain(blockchainType string)
	Stop()
}
type Links map[string]string // [name]hash

type Marshalled 

type Marshalled interface {
	Namespace() string
	ResourceType() string
	Name() string
	Version() string
	Hash() string
	Marshal() ([]byte, Links, error)
	Unmarshal([]byte, Links) error
}

type MessageProtocol 

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

MessageProtocol is a string that identifies a messaging protocol. The canonical form is: 

/<blockchain type>/<resource type>/<component type>/<version>

For example: 

/blocktop/block/luckyblock/v1
/blocktop/transaction/exchange/v2

func NewProtocol 

func NewProtocol(value string) *MessageProtocol

func NewProtocolMarshalled 

func NewProtocolMarshalled(blockchainName string, m Marshalled) *MessageProtocol

func NewProtocolParts 

func NewProtocolParts(blockchainName string, resourceType string, componentName string, version string) *MessageProtocol

func (*MessageProtocol) BlockchainName 

func (p *MessageProtocol) BlockchainName() string

func (*MessageProtocol) ComponentName 

func (p *MessageProtocol) ComponentName() string

func (*MessageProtocol) IsValid 

func (p *MessageProtocol) IsValid() bool

func (*MessageProtocol) ResourceType 

func (p *MessageProtocol) ResourceType() string

func (*MessageProtocol) SetBlockchainName 

func (p *MessageProtocol) SetBlockchainName(blockchainName string)

func (*MessageProtocol) SetComponentName 

func (p *MessageProtocol) SetComponentName(componentName string)

func (*MessageProtocol) SetResourceType 

func (p *MessageProtocol) SetResourceType(resourceType string)

func (*MessageProtocol) SetValue 

func (p *MessageProtocol) SetValue(value string) (ok bool)

func (*MessageProtocol) SetVersion 

func (p *MessageProtocol) SetVersion(version string)

func (*MessageProtocol) String 

func (p *MessageProtocol) String() string

func (*MessageProtocol) Version 

func (p *MessageProtocol) Version() string

type MessageReceiver 

type MessageReceiver func(*NetworkMessage)

type NetworkMessage 

type NetworkMessage struct {
	Data     []byte
	Links    Links
	Hash     string
	Protocol *MessageProtocol
	From     string
}

type NetworkNode 

type NetworkNode interface {
	Bootstrap(context.Context) error
	PeerID() string
	Listen(context.Context)
	Sign(data []byte) ([]byte, error)
	Verify(peerID string, data []byte, sig []byte, pubKey []byte) (bool, error)

	// Broadcast is a NetworkBroadcaster function that can be passed
	// around to any component that needs to broadcast to the P2P network.
	Broadcast([]*NetworkMessage)
	OnMessageReceived(MessageReceiver)
	Close()
}

type Store 

type Store interface {
	OpenBlock(blockNumber uint64) (StoreBlock, error)
	StoreBlock() StoreBlock
	Close()
	GetRoot() string
	Put(context.Context, Marshalled) error
	Get(ctx context.Context, hash string, obj Marshalled) error
	TreeGet(ctx context.Context, key string, obj Marshalled) error
	Hash(data []byte, links Links) (string, error)
}

type StoreBlock 

type StoreBlock interface {
	IsOpen() (bool, uint64)
	Submit(context.Context, Block) (root string, err error)
	GetRoot() string
	Commit(context.Context) error
	Revert() error
	TreePut(ctx context.Context, key string, obj Marshalled) error
	TreeGet(ctx context.Context, key string, obj Marshalled) error
}

type Transaction 

type Transaction interface {
	Marshalled
	Parties() map[string]Account // e.g. ["sender"]Account{x}
}

type TransactionHandler 

type TransactionHandler interface {
	Type() string
	ReceiveTransaction(*NetworkMessage) (Transaction, error)
	Execute(Transaction) (ok bool)
}

type URI 

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

URI is a string that identifies a resource in a blockchain. The canonical form is: 

<blockchain type>://<resource type>/<component type>/<version>/<id>

For example: 

blocktop://block/luckyblock/v1/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
blocktop://transaction/exchange/v2/fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210

func NewURI 

func NewURI(value string) *URI

func NewURIFromProtocol 

func NewURIFromProtocol(p *MessageProtocol, id string) *URI

func NewURIParts 

func NewURIParts(blockchainName string, resourceType string, componentName string, version string, id string) *URI

func (*URI) BlockchainName 

func (u *URI) BlockchainName() string

func (*URI) ComponentName 

func (u *URI) ComponentName() string

func (*URI) ID 

func (u *URI) ID() string

func (*URI) IsValid 

func (u *URI) IsValid() bool

func (*URI) ResourceType 

func (u *URI) ResourceType() string

func (*URI) SetBlockchainName 

func (u *URI) SetBlockchainName(blockchainName string)

func (*URI) SetComponentName 

func (u *URI) SetComponentName(componentName string)

func (*URI) SetID 

func (u *URI) SetID(id string)

func (*URI) SetResourceType 

func (u *URI) SetResourceType(resourceType string)

func (*URI) SetValue 

func (u *URI) SetValue(value string) (ok bool)

func (*URI) SetVersion 

func (u *URI) SetVersion(version string)

func (*URI) String 

func (u *URI) String() string

func (*URI) Version 

func (u *URI) Version() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.