Package convex.core

Class Belief

java.lang.Object

convex.core.data.AObject

convex.core.data.ACell

convex.core.data.ACountable<E>

convex.core.data.ADataStructure<MapEntry<K,V>>

convex.core.data.AMap<Keyword,ACell>

convex.core.data.ARecord

convex.core.Belief

All Implemented Interfaces:

IAssociative<Keyword,ACell>, IValidated, IWriteable, Map<Keyword,ACell>

public class Belief
extends ARecord

Class representing a Peer's view of the overall network consensus state. Belief is immutable, and is designed to be independent of any particular Peer so that it can be efficiently merged towards consensus. Belief can be merged with other Beliefs from the perspective of a Peer. This property is fundamental to the Convex consensus algorithm. "Sorry to be a wet blanket. Writing a description for this thing for general audiences is bloody hard. There's nothing to relate it to." – Satoshi Nakamoto

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K extends Object,V extends Object>

Field Summary

Fields inherited from class convex.core.data.ARecord

DEFAULT_VALUE

Fields inherited from class convex.core.data.ADataStructure

count

Fields inherited from class convex.core.data.ACell

cachedRef, EMPTY_ARRAY

Fields inherited from class convex.core.data.AObject

encoding

Method Summary

Modifier and Type	Method	Description
static boolean	compareOrders(Order oldOrder, Order newOrder)	Checks if a new Order should replace the current order when collecting Peer orders
static <V> double	computeVote(HashMap<V,Double> m)	Computes the total vote for all entries in a HashMap
static AVector<SignedData<Block>>	computeWinningOrder(HashMap<Order,Double> stakedOrders, long consensusPoint, double initialTotalStake)	Compute the new winning Order for this Peer, including any new blocks encountered
static Belief	create(AKeyPair kp, Order order)	Create a Belief with a single order signed by the given key pair, using initial timestamp.
static Belief	create(SignedData<Order>... orders)
static Belief	create(HashMap<AccountKey,SignedData<Order>> orderMap)
static Belief	createSingleOrder(AKeyPair kp)	Create a Belief with a single empty order.
int	encode(byte[] bs, int pos)	Writes this Cell's encoding to a byte array, including a tag byte which will be written first.
boolean	equals(Belief a)	Tests if this Belief is equal to another
boolean	equals(ACell a)	Checks for equality with another Cell.
int	estimatedEncodingSize()	Estimate the encoded data size for this Cell.
static Collection<SignedData<Order>>	extractOrders(ACell payload)	Extract a collection of Orders from a Cell, suitable for Belief merge
ACell	get(ACell k)	Gets the record field content for a given key, or null if not found.
RecordFormat	getFormat()	Gets the RecordFormat instance that describes this Record's layout
Order	getOrder(AccountKey address)	Gets the current Order for a given Address within this Belief.
BlobMap<AccountKey,SignedData<Order>>	getOrders()	Get the map of orders for this Belief
HashMap<AccountKey,SignedData<Order>>	getOrdersHashMap()	Gets a new HashMap containing all Orders
<R extends ACell> Ref<R>	getRef(int i)	Gets a numbered child Ref from within this Cell.
int	getRefCount()	Gets the number of Refs contained within this Cell.
byte	getTag()	Gets the tag byte for this record type.
static Belief	initial()	Gets an empty Belief
Belief	merge(MergeContext mc, Belief... beliefs)	The Belief merge function
Belief	mergeOrders(MergeContext mc, Belief b)
static double	prepareStakedOrders(AMap<AccountKey,SignedData<Order>> peerOrders, HashMap<AccountKey,Double> peerStakes, HashMap<Order,Double> dest)	Compute the total stake for every distinct Order seen.
Belief	proposeBlock(AKeyPair kp, SignedData<Block> signedBlock)
static Belief	read(Blob b, int pos)
static Belief	read(ByteBuffer bb)	Read a Belief from a ByteBuffer.
Belief	updateRefs(IRefFunction func)	Updates all Refs in this object using the given function.
void	validateCell()	Validates the local structure and invariants of this cell.
Belief	withOrders(BlobMap<AccountKey,SignedData<Order>> newOrders)	Updates this Belief with a new set of Chains for each peer address

Methods inherited from class convex.core.data.ARecord

accumulateEntrySet, accumulateKeySet, accumulateValues, assoc, assocEntry, containsKey, containsValue, dissoc, dissoc, empty, encodeRaw, entryAt, entrySet, forEach, get, getEntry, getEntryByHash, getKeyRefEntry, getKeys, getType, getValuesArray, isCanonical, isCVMValue, keySet, reduceEntries, reduceValues, toCanonical, toHashMap, values

Methods inherited from class convex.core.data.AMap

clear, conj, containsKey, containsKeyRef, containsValue, entryVector, filterValues, get, get, getElementRef, merge, print, put, putAll, remove, slice, slice

Methods inherited from class convex.core.data.ADataStructure

conjAll, count, isEmpty, size, toCVMString

Methods inherited from class convex.core.data.ACell

announce, announce, attachMemorySize, attachRef, cachedEncoding, cachedHash, calcMemorySize, createAnnounced, createEncoding, createPersisted, createPersisted, createRef, equals, getCanonical, getChildRefs, getEncoding, getEncodingLength, getHash, getMemorySize, getRef, hashCode, isCompletelyEncoded, isEmbedded, mark, mark, toString, validate, write

Methods inherited from class convex.core.data.AObject

attachEncoding, print, print

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove, replace, replace, replaceAll, size

Method Details

get

public ACell get(ACell k)

Description copied from class: ARecord

Gets the record field content for a given key, or null if not found.

Specified by:

get in class ARecord

Parameters:

k - Key to look up in this record

Returns:

Field value for the given key

updateRefs

public Belief updateRefs(IRefFunction func)

Description copied from class: ACell

Updates all Refs in this object using the given function. The function *must not* change the hash value of Refs, in order to ensure structural integrity of modified data structures. The implementation *should* re-attach any original encoding in order to prevent re-encoding or surplus hashing This is a building block for a very sneaky trick that enables use to do a lot of efficient operations on large trees of smart references. Must return the same object if no Refs are altered.

Overrides:

updateRefs in class ACell

Parameters:

func - Ref update function

Returns:

Cell with updated Refs

initial

public static Belief initial()

Gets an empty Belief

Returns:

Empty Belief

create

public static Belief create(AKeyPair kp,
 Order order)

Create a Belief with a single order signed by the given key pair, using initial timestamp.

Parameters:

kp - Peer Key pair with which to sign the order.

order - Order of blocks that the Peer is proposing

Returns:

new Belief representing the isolated belief of a single Peer.

create

public static Belief create(SignedData<Order>... orders)

create

public static Belief create(HashMap<AccountKey,SignedData<Order>> orderMap)

createSingleOrder

public static Belief createSingleOrder(AKeyPair kp)

Create a Belief with a single empty order. USeful for Peer startup.

Parameters:

kp - Keypair for Peer

Returns:

New Belief

merge

public Belief merge(MergeContext mc,
 Belief... beliefs)
             throws InvalidDataException

The Belief merge function

Parameters:

mc - MergeContext for Belief Merge

beliefs - An array of Beliefs. May contain nulls, which will be ignored.

Returns:

The updated merged belief with latest timestamp, or the same Belief if there is no change to Orders.

Throws:

InvalidDataException - In case of invalid data

mergeOrders

public Belief mergeOrders(MergeContext mc,
 Belief b)

compareOrders

public static boolean compareOrders(Order oldOrder,
 Order newOrder)

Checks if a new Order should replace the current order when collecting Peer orders

Parameters:

oldOrder - Current Order

newOrder - Potential new ORder

Returns:

computeWinningOrder

public static AVector<SignedData<Block>> computeWinningOrder(HashMap<Order,Double> stakedOrders,
 long consensusPoint,
 double initialTotalStake)

Compute the new winning Order for this Peer, including any new blocks encountered

Parameters:

stakedOrders - Amount of stake on each distinct Order

consensusPoint - Current consensus point

initialTotalStake - Total stake under consideration

Returns:

Vector of Blocks in winning Order

computeVote

public static <V> double computeVote(HashMap<V,Double> m)

Computes the total vote for all entries in a HashMap

Type Parameters:

V - The type of values used as keys in the HashMap

Parameters:

m - A map of values to votes

Returns:

The total voting stake

prepareStakedOrders

public static double prepareStakedOrders(AMap<AccountKey,SignedData<Order>> peerOrders,
 HashMap<AccountKey,Double> peerStakes,
 HashMap<Order,Double> dest)

Compute the total stake for every distinct Order seen. Stores results in a map of Orders to staked value.

Parameters:

peerOrders - A map of peer addresses to signed proposed Orders

peerStakes - A map of peers addresses to weighted stakes for each peer

dest - Destination hashmap to store the stakes for each Order

Returns:

The total stake of all chains among peers under consideration

withOrders

public Belief withOrders(BlobMap<AccountKey,SignedData<Order>> newOrders)

Updates this Belief with a new set of Chains for each peer address

Parameters:

newOrders - New map of peer keys to Orders

Returns:

The updated belief, or the same Belief if no change.

encode

public int encode(byte[] bs,
 int pos)

Description copied from class: ACell

Writes this Cell's encoding to a byte array, including a tag byte which will be written first. Cell must be canonical, or else an error may occur.

Specified by:

encode in interface IWriteable

Specified by:

encode in class ACell

Parameters:

bs - A byte array to which to write the encoding

pos - The offset into the byte array

Returns:

New position after writing

estimatedEncodingSize

public int estimatedEncodingSize()

Description copied from interface: IWriteable

Estimate the encoded data size for this Cell. Used for quickly sizing buffers. Implementations should try to return a size that is highly likely to contain the entire object when encoded, including the tag byte. Should not traverse soft Refs, i.e. must be usable on arbitrary partial data structures

Specified by:

estimatedEncodingSize in interface IWriteable

Overrides:

estimatedEncodingSize in class ARecord

Returns:

The estimated size for the binary representation of this object.

read

public static Belief read(ByteBuffer bb)
                   throws BadFormatException

Read a Belief from a ByteBuffer. Assumes tag already read.

Parameters:

bb - ByteBuffer to read from

Returns:

Belief instance

Throws:

BadFormatException - If encoding is invalid

read

public static Belief read(Blob b,
 int pos)
                   throws BadFormatException

Throws:

BadFormatException

getTag

public byte getTag()

Description copied from class: ARecord

Gets the tag byte for this record type. The Tag is the byte used to identify the record in the binary encoding.

Specified by:

getTag in class ARecord

Returns:

Record tag byte

getOrder

public Order getOrder(AccountKey address)

Gets the current Order for a given Address within this Belief.

Parameters:

address - Address of peer

Returns:

The chain for the peer within this Belief, or null if noy found.

getOrders

public BlobMap<AccountKey,SignedData<Order>> getOrders()

Get the map of orders for this Belief

Returns:

Orders map

validateCell

public void validateCell()
                  throws InvalidDataException

Description copied from class: ACell

Validates the local structure and invariants of this cell. Called by validate() super implementation. Should validate directly contained data, but should not validate all other structure of this cell. In particular, should not traverse potentially missing child Refs.

Specified by:

validateCell in class ACell

Throws:

InvalidDataException - If the Cell is invalid

equals

public boolean equals(ACell a)

Description copied from class: ACell

Checks for equality with another Cell. In general, Cells are considered equal if they have the same canonical representation, i.e. an identical encoding with the same hash value. Subclasses SHOULD override this if they have a more efficient equals implementation. MUST NOT require reads from Store.

Overrides:

equals in class ACell

Parameters:

a - Cell to compare with. May be null.

Returns:

True if this cell is equal to the other object

equals

public boolean equals(Belief a)

Tests if this Belief is equal to another

Parameters:

a - Belief to compare with

Returns:

true if equal, false otherwise

getRefCount

public int getRefCount()

Description copied from class: ACell

Gets the number of Refs contained within this Cell. This number is final / immutable for any given instance and is defined by the Cell encoding rules. WARNING: may not be valid id Cell is not canonical Contained Refs may be either external or embedded.

Specified by:

getRefCount in class ACell

Returns:

The number of Refs in this Cell

getRef

public <R extends ACell> Ref<R> getRef(int i)

Description copied from class: ACell

Gets a numbered child Ref from within this Cell. WARNING: May be unreliable is cell is not canonical

Overrides:

getRef in class ACell

Type Parameters:

R - Type of referenced Cell

Parameters:

i - Index of ref to get

Returns:

The Ref at the specified index

getOrdersHashMap

public HashMap<AccountKey,SignedData<Order>> getOrdersHashMap()

Gets a new HashMap containing all Orders

Returns:

HashMap of current orders

getFormat

public RecordFormat getFormat()

Description copied from class: ARecord

Gets the RecordFormat instance that describes this Record's layout

Specified by:

getFormat in class ARecord

Returns:

RecordFormat instance

extractOrders

public static Collection<SignedData<Order>> extractOrders(ACell payload)

Extract a collection of Orders from a Cell, suitable for Belief merge

Parameters:

payload - Cell to extra orders from

Returns:

Collection of signed orders

proposeBlock

public Belief proposeBlock(AKeyPair kp,
 SignedData<Block> signedBlock)