package byzcoin

Get desktop application:
View/edit binary Protocol Buffers messages

AddTxRequest requests to apply a new transaction to the ledger.

• required sint32 version = 1

  Version of the protocol

• required bytes skipchainid = 2

  SkipchainID is the hash of the first skipblock

• required ClientTransaction transaction = 3

  Transaction to be applied to the kv-store

• optional sint32 inclusionwait = 4

  How many block-intervals to wait for inclusion - missing value or 0 means return immediately.

• optional bytes prooffrom = 5

  ProofFrom is used to ask a proof from a given block. If this field is empty, the proof will start from the genesis block. The proof is returned only when InclusionWait is above 0.

• optional sint32 flags = 6

  Flags can hold additional flags to pass to the endpoint. Current flags supported are: - 1: leader check - don't propagate further

AddTxResponse is the reply after an AddTxRequest is finished.

• required sint32 version = 1

  Version of the protocol

• optional string error = 2

  Error message describes why the transaction failed.

• optional Proof proof = 3

  Proof of the block with the transaction.

Argument is a name/value pair that will be passed to the contract.

Used in: Delete, Invoke, Spawn

• required string name = 1

  Name can be any name recognized by the contract.

• required bytes value = 2

  Value must be binary marshalled

ChainConfig stores all the configuration information for one skipchain. It will be stored under the key [32]byte{} in the tree.

• required sint64 blockinterval = 1

• required onet.Roster roster = 2

• required sint32 maxblocksize = 3

• repeated string darccontractids = 4

CheckAuthorization returns the list of actions that could be executed if the signatures of the given identities are present and valid

• required sint32 version = 1

  Version of the protocol

• required bytes byzcoinid = 2

  ByzCoinID where to look up the darc

• required bytes darcid = 3

  DarcID that holds the rules

• repeated darc.Identity identities = 4

  Identities that will sign together

CheckAuthorizationResponse returns a list of Actions that the given identities can execute in the given darc. The list can be empty, which means that the given identities have now authorization in that darc at all.

• repeated string actions = 1

CheckStateChangeValidity is a request to get the list of state changes belonging to the same block as the targeted one to compute the hash

• required bytes skipchainid = 1

• required bytes instanceid = 2

• required uint64 version = 3

CheckStateChangeValidityResponse is the response with the list of state changes so that the hash can be compared against the one in the block

• repeated StateChange statechanges = 1

• required bytes blockid = 2

ClientTransaction is a slice of Instructions that will be applied in order. If any of the instructions fails, none of them will be applied. InstructionsHash must be the hash of the concatenation of all the instruction hashes (see the Hash method in Instruction), this hash is what every instruction must sign for the transaction to be valid.

Used in: AddTxRequest, TxResult

• repeated Instruction instructions = 1

Coin is a generic structure holding any type of coin. Coins are defined by a genesis coin instance that is unique for each type of coin.

Used in: calypso.Write, personhood.RoPaSciStruct, personhood.SpawnerStruct

• required bytes name = 1

  Name points to the genesis instance of that coin.

• required uint64 value = 2

  Value is the total number of coins of that type.

CreateGenesisBlock asks the cisc-service to set up a new skipchain.

• required sint32 version = 1

  Version of the protocol

• required onet.Roster roster = 2

  Roster defines which nodes participate in the skipchain.

• required darc.Darc genesisdarc = 3

  GenesisDarc defines who is allowed to write to this skipchain.

• required sint64 blockinterval = 4

  BlockInterval in int64 as nanoseconds since the Unix Epoch. Before VersionRollup, this was the time the leader waited between a signed block and asking for new transactions. With VersionRollup, the BlockInterval is only used to calculate the maximum protocol timeouts and the time-window of acceptance of a new block.

• optional sint32 maxblocksize = 5

  Maximum block size. Zero (or not present in protobuf) means use the default, 4 megs.

• repeated string darccontractids = 6

  DarcContracts is the set of contracts that can be parsed as a DARC. At least one contract must be given.

CreateGenesisBlockResponse holds the genesis-block of the new skipchain.

• required sint32 version = 1

  Version of the protocol

• optional skipchain.SkipBlock skipblock = 2

  Skipblock of the created skipchain or empty if there was an error.

DBKeyValue represents one element in bboltdb

Used in: DownloadStateResponse

• required bytes key = 1

• required bytes value = 2

DataBody is stored in the body of the skipblock, and it's hash is stored in the DataHeader.

• repeated TxResult txresults = 1

DataHeader is the data passed to the Skipchain

• required bytes trieroot = 1

  TrieRoot is the root of the merkle tree of the colleciton after applying the valid transactions.

• required bytes clienttransactionhash = 2

  ClientTransactionHash is the sha256 hash of all the transactions in the body

• required bytes statechangeshash = 3

  StateChangesHash is the sha256 of all the StateChanges generated by the accepted transactions.

• required sint64 timestamp = 4

  Timestamp is a Unix timestamp in nanoseconds.

• optional sint32 version = 5

  Version is the version of ByzCoin at the creation of the block.

DebugRemoveRequest asks the conode to delete the given byzcoin-instance from its database. It needs to be signed by the private key of the conode.

• required bytes byzcoinid = 1

• required bytes signature = 2

DebugRequest returns the list of all byzcoins if byzcoinid is empty, else it returns a dump of all instances if byzcoinid is given and exists.

• optional bytes byzcoinid = 1

DebugResponse is returned from the server. Either Byzcoins is returned and holds a list of all byzcoin-instances, together with the genesis block and the latest block, or it returns a dump of all instances in the form of a slice of StateChangeBodies.

• repeated DebugResponseByzcoin byzcoins = 1

• repeated DebugResponseState dump = 2

DebugResponseByzcoin represents one byzcoinid with the genesis and the latest block, as it is for debugging reasons, we trust the node and don't return any proof.

Used in: DebugResponse

• required bytes byzcoinid = 1

• optional skipchain.SkipBlock genesis = 2

• optional skipchain.SkipBlock latest = 3

DebugResponseState holds one key/state pair of the response.

Used in: DebugResponse

• required bytes key = 1

• required StateChangeBody state = 2

Delete removes the instance. The contract might enforce conditions that must be true before a Delete is executed.

Used in: Instruction

• required string contractid = 1

  ContractID represents the kind of contract that is being deleted.

• repeated Argument args = 2

  Args holds all data necessary to delete the instance.

DownloadState requests the current global state of that node. If it is the first call to the service, then Reset must be true, else an error will be returned, or old data might be used.

• required bytes byzcoinid = 1

  ByzCoinID of the state to download

• required uint64 nonce = 2

  Nonce is 0 for a new download, else it must be equal to the nonce returned in DownloadStateResponse. In case Nonce is non-zero, but doesn't correspond to the current session, an error is returned, as only one download-session can be active at any given moment.

• required sint32 length = 3

  Length of the statechanges to download

DownloadStateResponse is returned by the service. If there are no Instances left, then the length of Instances is 0.

• repeated DBKeyValue keyvalues = 1

  KeyValues holds a copy of a slice of DBKeyValues directly from bboltdb

• required uint64 nonce = 2

  Nonce to be used for the download. The Nonce is generated by the server, and will be set for every subsequent reply, too.

• optional sint32 total = 3

  Total key/value pairs.

GetAllByzCoinIDsRequest is a request to get all the Byzcoin chains from a server.

(message has no fields)

GetAllByzCoinIDsResponse contains the list of Byzcoin chains known by a server.

• repeated bytes ids = 1

GetAllInstanceVersion is a request asking for the list of state changes of a given instance

• required bytes skipchainid = 1

• required bytes instanceid = 2

GetAllInstanceVersionResponse is the response that contains the list of state changes of a instance

• repeated GetInstanceVersionResponse statechanges = 1

GetInstanceVersion is a request asking the service to fetch the version of the given instance

• required bytes skipchainid = 1

• required bytes instanceid = 2

• required uint64 version = 3

GetInstanceVersionResponse is the response for both GetInstanceVersion and GetLastInstanceVersion. It contains the state change if it exists and the block index where it has been applied

Used in: GetAllInstanceVersionResponse

• required StateChange statechange = 1

• required sint32 blockindex = 2

GetLastInstanceVersion is request asking for the last version of a given instance

• required bytes skipchainid = 1

• required bytes instanceid = 2

GetProof returns the proof that the given key is in the trie.

• required sint32 version = 1

  Version of the protocol

• required bytes key = 2

  Key is the key we want to look up

• required bytes id = 3

  ID is any block that is known to us in the skipchain, can be the genesis block or any later block. The proof returned will be starting at this block.

• optional bytes mustcontainblock = 4

  MustContainBlock when provided informs the server that the proof should include this block.

GetProofResponse can be used together with the Genesis block to proof that the returned key/value pair is in the trie.

• required sint32 version = 1

  Version of the protocol

• required Proof proof = 2

  Proof contains everything necessary to prove the inclusion of the included key/value pair given a genesis skipblock.

GetSignerCounters is a request to get the latest version for the specified identity.

• repeated string signerids = 1

• required bytes skipchainid = 2

GetSignerCountersResponse holds the latest version for the identity in the request.

• repeated uint64 counters = 1

• optional uint64 index = 2

  Index contains the trie index where the counters have been extracted so clients can use it to make sure the counters are up-to-date.

GetUpdatesReply only sends back the instances that have a new version, but will not send any proof for an instance that didn't change.

• repeated trie.Proof proofs = 1

• repeated skipchain.ForwardLink links = 2

• optional skipchain.SkipBlock latest = 3

GetUpdatesRequest allows to request changes to existing instances by sending a slice of known versions. If the LatestBlockID is given, the method checks if it corresponds to the latest block. The usage of LatestBlockID is discouraged. SkipchainID should be given instead of LatestBLockID to fetch the latest versions of the instance from the given skipchain.

• repeated IDVersion instances = 1

• required uint64 flags = 2

• optional bytes latestblockid = 3

• optional bytes skipchainid = 4

IDVersion holds the InstanceID and the latest known version of an instance.

Used in: GetUpdatesRequest

• required bytes id = 1

• required uint64 version = 2

Instruction holds only one of Spawn, Invoke, or Delete

Used in: ClientTransaction

• required bytes instanceid = 1

  InstanceID is either the instance that can spawn a new instance, or the instance that will be invoked or deleted.

• optional Spawn spawn = 2

  Spawn creates a new instance.

• optional Invoke invoke = 3

  Invoke calls a method of an existing instance.

• optional Delete delete = 4

  Delete removes the given instance.

• repeated uint64 signercounter = 5

  SignerCounter must be set to a value that is one greater than what was in the last instruction signed by the same signer. Every counter must map to the corresponding element in Signature. The initial counter is 1. Overflow is allowed.

• repeated darc.Identity signeridentities = 6

  SignerIdentities are the identities of all the signers.

• repeated bytes signatures = 7

  Signatures that are verified using the Darc controlling access to the instance.

  synthetic is a private field indicating that the instruction has been artificially created, which can give it additional rights (see Instruction.usesForbiddenIdentities()). version is a private field that can allow an instruction to be passed around with the context of a block with a specific version. This field must be the last field of the struct, so that the protobuf-library enumerates the fields correctly.

Invoke calls a method of an existing instance which will update its internal state.

Used in: Instruction

• required string contractid = 1

  ContractID represents the kind of contract that is being invoked.

• required string command = 2

  Command is interpreted by the contract.

• repeated Argument args = 3

  Args holds all data necessary for the successful execution of the command.

PaginateRequest is a request to get NumPages times the consecutive list of PageSize blocks.

• required bytes startid = 1

  The first block to fetch

• required uint64 pagesize = 2

  Determines the length of the Blocks attribute in the PaginateResponse. The list contains PageSize consecutive blocks

• required uint64 numpages = 3

  The number of (asynchrounous) requests the service will return to the client. Requests are send in a consecutive order wrt their list of blocks

• required bool backward = 4

  If true then blocks are consecutive in the reverse order, ie. following backward links.

PaginateResponse is a reponse from a PaginateRequest.

• repeated skipchain.SkipBlock blocks = 1

  A list of consecutive blocks

• required uint64 pagenumber = 2

  The page number index: relevant if the clients asked for more than one asynchrounous reply from the service.

• required bool backward = 3

  Tells if the result contains consecutive blocks in a reversed order.

• required uint64 errorcode = 4

  Used to tell the client if an error occured. Any error code not equal to 0 means that something special happened.

• repeated string errortext = 5

  A list of error messages in case something special happened.

Proof represents everything necessary to verify a given key/value pair is stored in a skipchain. The proof is in three parts: 1. InclusionProof proves the presence or absence of the key. In case of the key being present, the value is included in the proof. 2. Latest is used to verify the Merkle tree root used in the proof is stored in the latest skipblock. 3. Links proves that the latest skipblock is part of the skipchain. This Structure could later be moved to cothority/skipchain.

Used in: AddTxResponse, GetProofResponse, calypso.CreateLTS, calypso.DecryptKey, calypso.ReshareLTS, calypso.UpdateValidPeers

• required trie.Proof inclusionproof = 1

  InclusionProof is the deserialized InclusionProof

• required skipchain.SkipBlock latest = 2

  Providing the latest skipblock to retrieve the Merkle tree root.

• repeated skipchain.ForwardLink links = 3

  Proving the path to the latest skipblock. The first ForwardLink has an empty-sliced `From` and the genesis-block in `To`, together with the roster of the genesis-block in the `NewRoster`.

ResolveInstanceID is the request for resolving the instance ID based on the Darc ID and the name.

• required bytes skipchainid = 1

• required bytes darcid = 2

• required string name = 3

ResolvedInstanceID is the result of the instance ID resolution.

• required bytes instanceid = 1

Spawn is called upon an existing instance that will spawn a new instance.

Used in: Instruction

• required string contractid = 1

  ContractID represents the kind of contract that is being spawned.

• repeated Argument args = 2

  Args holds all data necessary to spawn the new instance.

StateChange is one new state that will be applied to the collection.

Used in: CheckStateChangeValidityResponse, GetInstanceVersionResponse

• required sint32 stateaction = 1

  StateAction can be any of Create, Update, Remove

• required bytes instanceid = 2

  InstanceID of the state to change

• required string contractid = 3

  ContractID points to the contract that can interpret the value

• required bytes value = 4

  Value is the data needed by the contract

• required bytes darcid = 5

  DarcID is the Darc controlling access to this key.

• required uint64 version = 6

  Version is the monotonically increasing version of the instance

StateChangeBody represents the body part of a state change, which is the part that needs to be serialised and stored in a merkle tree.

Used in: DebugResponseState

• required sint32 stateaction = 1

• required string contractid = 2

• required bytes value = 3

• required uint64 version = 4

• required bytes darcid = 5

StreamingRequest is a request asking the service to start streaming blocks on the chain specified by ID.

• required bytes id = 1

StreamingResponse is the reply (block) that is streamed back to the client

• optional skipchain.SkipBlock block = 1

TxResult holds a transaction and the result of running it.

Used in: DataBody

• required ClientTransaction clienttransaction = 1

• required bool accepted = 2