11.4 Messaggi Blockchain

11.4.1 Intro

Definizione del messaggio utilizzata per la comunicazione con il servizio blockchain utilizzando il canale esposto dal servizio blockchain. Questo formato è utilizzato da tutti i componenti che richiedono una qualche forma di comunicazione con la blockchain. Entrambi i componenti strettamente interni come il componente bootstrap del nodo e il tracer e tutti i componenti che forniscono un'interfaccia al mondo esterno come p2p, bridge, rest services utilizzano questo formato di messaggio. La struttura dei messaggi è data in un formato pseudo json/asn1/rustacean. Quando la serializzazione e la deserializzazione devono essere eseguite dal servizio blockchain, il mittente deve impacchettare la struttura utilizzando il formato anonimo "MessagePack".

11.4.2 Definizioni delle strutture di supporto

CHOICE: è possibile selezionare un solo elemento dall'insieme indicato.

FLAG : più elementi possono essere selezionati dall'insieme dato.

SequenceOf : un array di elementi omogenei.

ByteBuffer := SequenceDi u8

Ticket := MultiHash(MessagePack(Transazione::Dati))

11.4.3 Messaggio Blockchain

Un messaggio che può essere consumato e prodotto dal servizio blockchain.

Message { type: u8, body: MessageBody, }

Tipi di corpo del messaggio insieme ai valori dei tag di tipo utilizzati per la serializzazione:

MessageBody : CHOICE { Exception = 0, Subscribe = 1, Unsubscribe = 2, PutTransactionRequest = 3, PutTransactionResponse = 4, GetTransactionRequest = 5, GetTransactionResponse = 6, GetReceiptRequest = 7, GetReceiptResponse = 8, GetBlockRequest = 9, GetBlockResponse = 10, GetAccountRequest = 11, GetAccountResponse = 12, Stop = 254, Packed = 255, }

Il corpo del messaggio è "appiattito" nella struttura del messaggio, il che significa che non deve essere applicato alcun livello di nidificazione aggiuntivo. Ad esempio, un messaggio di sottoscrizione viene serializzato in quanto definito come:

Message { type: 1, id: String, event: Event, packed: bool, }

Messaggio “Stop”. È un messaggio speciale per fermare il servizio blockchain. Come decisione progettuale, per impedire ai componenti esterni di interrompere il servizio blockchain, questo messaggio viene accettato solo quando proviene da un componente interno. Si presume che solo i messaggi compressi provengano da un componente esterno.

11.4.4 Subscribe

Consiste nella sottoscrizione agli eventi della blockchain T.R.I.N.C.I. Tale sottoscrizione permette di ricevere i messaggi già impacchettati. Questa opzione può essere utile per servizi di inoltro come p2p e bridge.

Subscribe { id: String, // Subscriber id event: Event, // Bitflags with events we want start receiving packed: bool, // Receive already packed data (MessagePack) }

Event : FLAG { Transaction, // receive a GetTransactionResponse when a new (good) tx is received Block, // receive a GetBlockResponse when a block is generated Request, // receive any request that the blockchain is trying to send out }

11.4.5 Unsubscribe

Unsubscribe agli eventi della blockchains.

Unsubscribe { id: String, // Subscriber id event: Event, // Bitflags with events we want stop receiving }

11.4.6 Put transaction

Invia una nuova transazione. La richiesta può essere confermata o meno. Quando viene richiesta la conferma, il servizio blockchain invierà una risposta contenente il risultato di invio corrispondente alla transazione. In caso di successo, il risultato dell'invio è il ticket della transazione (hash). In caso di errore, il risultato contiene il motivo dell'errore come stringa.

PutTransactionRequest { confirmed: bool, // If we require a confirmation tx: Transaction }

PutTransactionResponse { hash: Ticket }

11.4.7 Get Transaction

Ottieni una transazione con un ticket di transazione.

GetTransactionRequest { hash: Ticket }

GetTransactionResponse := { tx: Transaction }

11.4.8 Get Receipt

Ottieni una ricevuta di transazione con un ticket di transazione.

GetReceiptRequest := { hash: Ticket }

GetReceiptResponse := { rx: Receipt }

11.4.9 Get Block

Ottieni un contenuto di blocco. Facoltativamente permette di ottenere gli hash delle transazioni eseguite dal blocco specificato.

GetBlockRequest := { height: u64 // Block height (offset from the genesis block) txs: bool // Fetch transactions tickets as well }

GetBlockResponse := { block: Block txs: TransactionHashes }

TransactionsHashes : CHOICE { null, // Null if BlockRequest::txs is false SequenceOf Ticket // Sequence of block transaction tickets }

11.4.10 Get Account

Ottieni un contenuto dell'account.

GetAccountRequest := { id: String, // Account identifier data: SequenceOf string // Account data keys (may be empty) }

GetAccountResponse := { res: Account, data: SequenceOf DataResult }

DataResult : CHOICE { ByteBuffer, Null }

11.4.11 Exception

Qualcosa è andato storto durante l'elaborazione di un messaggio confermato. Questo messaggio contiene un messaggio di errore insieme all'origine.

Exception := { kind: string, source: string, }

11.4.12 Packed

Messaggio generalmente proveniente da una fonte esterna e inoltrato "così com'è" al servizio blockchain. Il messaggio compresso deve contenere ricorsivamente un messaggio serializzato in formato MessagePack. Il messaggio viene quindi deserializzato dal servizio blockchain prima di un'ulteriore elaborazione. Anche una risposta a un messaggio ricevuto come Packed viene inviata come Packed. Per motivi di sicurezza questo tipo di messaggio non può contenere un messaggio Stop.

Packed := ByteBuffer