ch.epfl.dedis.byzcoin

Class ByzCoinRPC

java.lang.Object

ch.epfl.dedis.byzcoin.ByzCoinRPC

Direct Known Subclasses:

CalypsoRPC

public class ByzCoinRPC
extends Object

Class ByzCoinRPC interacts with the byzcoin service of a conode. It can either start a new byzcoin service (this needs to be secured somehow) or link to an existing byzcoin service.

ByzCoinRPC is the new skipchain service of the cothority that allows batching of transactions and simplified proofs. It is a permissioned blockchain with high throughput (100-1000 transactions) and a byzantine-tolerant consensus algorithm.

Field Summary

Fields

Modifier and Type	Field and Description
static int	currentVersion

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ByzCoinRPC() For use by fromByzcoin
protected	ByzCoinRPC(ByzCoinRPC bc) For use by CalypsoRPC
	ByzCoinRPC(Roster r, Darc d, java.time.Duration blockInterval) This instantiates a new byzcoin object by asking the cothority to set up a new byzcoin.

Method Summary

Modifier and Type	Method and Description
List<String>	checkAuthorization(DarcId id, List<Identity> identities) CheckAuthorization asks ByzCoin which of the rules stored in the latest version of the darc given by id can be resolved with a combination of signatures given by identities.
boolean	checkLiveness() Verifies if the nodes representing the cothority are alive and reply to a ping.
boolean	checkStateChangeValidity(StateChange sc) Checks if the state change is valid or has been tempered
static ByzCoinRPC	fromByzCoin(Roster roster, SkipblockId skipchainId) Constructs a ByzCoinRPC from a known configuration.
List<StateChange>	getAllInstanceVersion(InstanceId id) Fetches all the state changes of the given instance
Block	getBlock(SkipblockId id) Fetches a given block from the skipchain and returns the corresponding Block.
Config	getConfig()
SkipBlock	getGenesisBlock()
Darc	getGenesisDarc()
SecureDarcInstance	getGenesisDarcInstance()
StateChange	getInstanceVersion(InstanceId id, long version) Fetches the state change for the given version and instance
StateChange	getLastInstanceVersion(InstanceId id) Fetches the most recent state change for the given instance
Block	getLatestBlock() Fetches the latest block from the Skipchain and returns the corresponding Block.
Proof	getProof(InstanceId id) Gets a proof from byzcoin to show that a given instance is stored in the global state.
Roster	getRoster()
SignerCounters	getSignerCounters(List<String> signerIDs) Gets the signer counters for the signer IDs.
SkipchainRPC	getSkipchain() This should be used with caution.
Subscription	getSubscription() Getter for the subscription object.
static Darc	makeGenesisDarc(Signer admin, Roster roster) Creates a genesis darc to use for the initialisation of Byzcoin.
ClientTransactionId	sendTransaction(ClientTransaction t) Sends a transaction to byzcoin, but doesn't wait for the inclusion of this transaction in a block.
ClientTransactionId	sendTransactionAndWait(ClientTransaction t, int wait) Sends a transaction to byzcoin and waits for up to 'wait' blocks for the transaction to be included in the global state.
void	setBlockInterval(java.time.Duration newInterval, List<Signer> admins, List<Long> adminCtrs, int wait) Sets the new block interval that ByzCoin uses to create new block.
void	setMaxBlockSize(int newMaxSize, List<Signer> admins, List<Long> adminCtrs, int wait) Sets the new block interval that ByzCoin uses to create new block.
void	setRoster(Roster newRoster, List<Signer> admins, List<Long> adminCtrs, int wait) Change the current roster of the ByzCoin ledger.
java.util.stream.Stream<SkipBlock>	subscribeSkipBlock() Subscribe to an infinite stream of future SkipBlocks.
void	subscribeSkipBlock(Subscription.SkipBlockReceiver sbr) Subscribes to all new skipBlocks that might arrive.
byte[]	toBytes()
void	unsubscribeBlock(Subscription.SkipBlockReceiver sbr) Unsubscribes a BlockReceiver.
void	update() Fetches the latest configuration and genesis darc from byzcoin.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

currentVersion

public static final int currentVersion

See Also:

Constant Field Values

Constructor Detail

ByzCoinRPC

public ByzCoinRPC(Roster r,
                  Darc d,
                  java.time.Duration blockInterval)
           throws CothorityException

This instantiates a new byzcoin object by asking the cothority to set up a new byzcoin.

Parameters:

r - is the roster to be used

d - is the genesis darc

blockInterval - is the block interval between two blocks

Throws:

CothorityException - if something goes wrong

ByzCoinRPC

protected ByzCoinRPC()

For use by fromByzcoin

ByzCoinRPC

protected ByzCoinRPC(ByzCoinRPC bc)

For use by CalypsoRPC

Parameters:

bc - the ByzCoinRPC to copy the config from.

Method Detail

sendTransaction

public ClientTransactionId sendTransaction(ClientTransaction t)
                                    throws CothorityException

Sends a transaction to byzcoin, but doesn't wait for the inclusion of this transaction in a block. Once the transaction has been sent, you need to poll to verify if it has been included or not.

Parameters:

t - is the client transaction holding one or more instructions to be sent to byzcoin.

Returns:

the client transaction

Throws:

CothorityException - if something goes wrong if something goes wrong

sendTransactionAndWait

public ClientTransactionId sendTransactionAndWait(ClientTransaction t,
                                                  int wait)
                                           throws CothorityCommunicationException

Sends a transaction to byzcoin and waits for up to 'wait' blocks for the transaction to be included in the global state. If more than 'wait' blocks are created and the transaction is not included, an exception will be raised.

Parameters:

t - is the client transaction holding one or more instructions to be sent to byzcoin.

wait - indicates the number of blocks to wait for the transaction to be included.

Returns:

ClientTransactionID the transaction ID

Throws:

CothorityCommunicationException - if the transaction has not been included within 'wait' blocks.

getProof

public Proof getProof(InstanceId id)
               throws CothorityCommunicationException,
                      CothorityCryptoException

Gets a proof from byzcoin to show that a given instance is stored in the global state.

Parameters:

id - is the id of the instance to be fetched

Returns:

the proof

Throws:

CothorityCommunicationException - if something goes wrong

CothorityCryptoException - if the verification fails

getSignerCounters

public SignerCounters getSignerCounters(List<String> signerIDs)
                                 throws CothorityCommunicationException

Gets the signer counters for the signer IDs. The counters must be set correctly in the instructions for them to be accepted by byzcoin. Every counter maps to a signer, if the most recent instruction is signed by the signer at count n, then the next instruction that the same signer signs must be on counter n+1.

Parameters:

signerIDs - the list of signer IDs

Returns:

The corresponding coutners for the given IDs

Throws:

CothorityCommunicationException - if something goes wrong

update

public void update()
            throws CothorityException

Fetches the latest configuration and genesis darc from byzcoin.

Throws:

CothorityException - if something goes wrong if something goes wrong

checkLiveness

public boolean checkLiveness()

Verifies if the nodes representing the cothority are alive and reply to a ping.

Returns:

true if all nodes are live, false if one or more are not responding.

toBytes

public byte[] toBytes()

Returns:

a byte representation of this byzcoin object.

getConfig

public Config getConfig()

Returns:

current configuration

getGenesisDarc

public Darc getGenesisDarc()

Returns:

current genesis darc

getGenesisDarcInstance

public SecureDarcInstance getGenesisDarcInstance()
                                          throws CothorityException

Returns:

the darc instance of the genesis darc.

Throws:

CothorityException - if something goes wrong if something goes wrong

getGenesisBlock

public SkipBlock getGenesisBlock()

Returns:

the genesis block of the ledger.

getRoster

public Roster getRoster()

Returns:

the roster responsible for the ledger

getBlock

public Block getBlock(SkipblockId id)
               throws CothorityCommunicationException,
                      CothorityCryptoException

Fetches a given block from the skipchain and returns the corresponding Block.

Parameters:

id - hash of the skipblock to fetch

Returns:

a Block representation of the skipblock

Throws:

CothorityCommunicationException - if it couldn't contact the nodes

CothorityCryptoException - if there's a problem with the cryptography

getLatestBlock

public Block getLatestBlock()
                     throws CothorityException

Fetches the latest block from the Skipchain and returns the corresponding Block.

Returns:

a Block representation of the skipblock

Throws:

CothorityCryptoException - if there's a problem with the cryptography

CothorityException

checkAuthorization

public List<String> checkAuthorization(DarcId id,
                                       List<Identity> identities)
                                throws CothorityCommunicationException

CheckAuthorization asks ByzCoin which of the rules stored in the latest version of the darc given by id can be resolved with a combination of signatures given by identities. Each identity can be of any type. If it is a darc, then any "_sign" rule given by that darc will be accepted.

Parameters:

id - the base id of the darc to be searched for

identities - a list of identities that might sign

Returns:

a list of actions that are allowed by any possible combination of signature from identities

Throws:

CothorityCommunicationException - if something goes wrong

getInstanceVersion

public StateChange getInstanceVersion(InstanceId id,
                                      long version)
                               throws CothorityCommunicationException

Fetches the state change for the given version and instance

Parameters:

id - the instance ID

version - the version of the state change

Returns:

the state change

Throws:

CothorityCommunicationException - if the state change doesn't exist or something went wrong

getLastInstanceVersion

public StateChange getLastInstanceVersion(InstanceId id)
                                   throws CothorityCommunicationException

Fetches the most recent state change for the given instance

Parameters:

id - the instance ID

Returns:

the state change

Throws:

CothorityCommunicationException - if the instance doesn't exist or something went wrong

getAllInstanceVersion

public List<StateChange> getAllInstanceVersion(InstanceId id)
                                        throws CothorityCommunicationException

Fetches all the state changes of the given instance

Parameters:

id - the instance ID

Returns:

the list of state changes

Throws:

CothorityCommunicationException - if the instance doesn't exist or something went wrong

checkStateChangeValidity

public boolean checkStateChangeValidity(StateChange sc)
                                 throws CothorityCommunicationException

Checks if the state change is valid or has been tempered

Parameters:

sc - the state change

Returns:

true if the state change is valid

Throws:

CothorityCommunicationException - if something went wrong

getSkipchain

public SkipchainRPC getSkipchain()

This should be used with caution. Every time you use this, please open an issue in github and tell us why you think you need this. We'll try to fix it then!

Returns:

the underlying skipchain service.

subscribeSkipBlock

public void subscribeSkipBlock(Subscription.SkipBlockReceiver sbr)
                        throws CothorityCommunicationException

Subscribes to all new skipBlocks that might arrive. The subscription is implemented using a polling approach until we have a working streaming solution.

Parameters:

sbr - is a SkipBlockReceiver that will be called with any new block(s) available.

Throws:

CothorityCommunicationException - if something goes wrong

subscribeSkipBlock

public java.util.stream.Stream<SkipBlock> subscribeSkipBlock()
                                                      throws CothorityCommunicationException

Subscribe to an infinite stream of future SkipBlocks. Note that you need to give a limit or the thread will hang indefinitely

Each subscription request uses its own connection and the stream must be correctly closed to clean the resources

Throws:

CothorityCommunicationException - if something goes wrong when establishing the connection

unsubscribeBlock

public void unsubscribeBlock(Subscription.SkipBlockReceiver sbr)

Unsubscribes a BlockReceiver.

Parameters:

sbr - the SkipBlockReceiver to unsubscribe.

setRoster

public void setRoster(Roster newRoster,
                      List<Signer> admins,
                      List<Long> adminCtrs,
                      int wait)
               throws CothorityException

Change the current roster of the ByzCoin ledger. You're only allowed to change one node at a time, because the system needs to be able to contact previous nodes. When removing nodes, there is a possibility of future proofs getting bigger, as it will be impossible to create forwardlinks.

When adding new nodes, it will take at least two blocks until they are completely active and ready to participate in the consensus. This is due to the time it takes for those blocks to download the global state.

Parameters:

newRoster - a new roster with one addition, one removal or one change

admins - a list of admins needed to sign off on the change

adminCtrs - a list of monotonically increasing counters for every admin

wait - how many blocks to wait for the new config to go in

Throws:

CothorityException - if something went wrong.

setBlockInterval

public void setBlockInterval(java.time.Duration newInterval,
                             List<Signer> admins,
                             List<Long> adminCtrs,
                             int wait)
                      throws CothorityException

Sets the new block interval that ByzCoin uses to create new block. The actual interval between two block in the current implementation is guaranteed to be at least 1 second higher, depending on the network delays and the number of transactions to include.

The chosen interval can not be smaller than 5 seconds.

Parameters:

newInterval - how long to wait before starting to assemble a new block

admins - a list of admins needed to sign off the new configuration

adminCtrs - a list of monotonically increasing counters for every admin

wait - how many blocks to wait for the new config to go in

Throws:

CothorityException

setMaxBlockSize

public void setMaxBlockSize(int newMaxSize,
                            List<Signer> admins,
                            List<Long> adminCtrs,
                            int wait)
                     throws CothorityException

Sets the new block interval that ByzCoin uses to create new block. The actual interval between two block in the current implementation is guaranteed to be at least 1 second higher, depending on the network delays and the number of transactions to include.

The chosen interval can not be smaller than 5 seconds.

Parameters:

newMaxSize - new maximum size of the assembled blocks.

admins - a list of admins needed to sign off the new configuration

adminCtrs - a list of monotonically increasing counters for every admin

wait - how many blocks to wait for the new config to go in

Throws:

CothorityException

fromByzCoin

public static ByzCoinRPC fromByzCoin(Roster roster,
                                     SkipblockId skipchainId)
                              throws CothorityException

Constructs a ByzCoinRPC from a known configuration. The constructor will communicate with the service to populate other fields and perform verification.

Parameters:

roster - the roster to talk to

skipchainId - the ID of the genesis skipblock, aka skipchain ID

Returns:

a new ByzCoinRPC object, connected to the requested roster and chain.

Throws:

CothorityException - if something goes wrong

makeGenesisDarc

public static Darc makeGenesisDarc(Signer admin,
                                   Roster roster)
                            throws CothorityCryptoException

Creates a genesis darc to use for the initialisation of Byzcoin.

Parameters:

admin - the admin of Byzcoin

roster - the nodes of Byzcoin

Returns:

a Darc with the correct rights, also for the view_change.

Throws:

CothorityCryptoException - if there's a problem with the cryptography

getSubscription

public Subscription getSubscription()

Getter for the subscription object.

Returns:

the Subscription