exonum

TOC

如何創建服務

Cryptocurrency Tutorial: How to Create Services · exonum/exonum-doc

Exonum uses Protobuf as its serialization format for storage of data. Thus, we need to describe our structures using the Protobuf interface description language first.

syntax = "proto3";

// Allows to use `exonum.PublicKey` structure already described in `exonum`
// library.
import "helpers.proto";

// Wallet structure used to persist data within the service.
message Wallet {
  exonum.PublicKey pub_key = 1;
  string name = 2;
  uint64 balance = 3;
}

// Transaction type for creating a new wallet.
message TxCreateWallet {
  // UTF-8 string with the owner's name.
  string name = 1;
}

// Transaction type for transferring tokens between two wallets.
message TxTransfer {
  // Public key of the receiver.
  exonum.PublicKey to = 1;
  // Number of tokens to transfer from the sender's account to the receiver's
  // account.
  uint64 amount = 2;
  // Auxiliary number to guarantee non-idempotence of transactions.
  uint64 seed = 3;
}

如何生成 Google Protocol Buffers 文件

exonum/exonum/src/proto/schema/exonum at master · exonum/exonum

git clone https://github.com/exonum/exonum.git /tmp/src/exonum
bash tc.sh --gen-proto-doc /tmp/src/exonum/exonum/src/proto/schema/exonum /tmp/output.md

Generated Date:2019-09-12T11:31:08+08:00

Protocol Documentation

Table of Contents

Top

tests.proto

BlockchainTestTxA

FieldTypeLabelDescription
auint64

BlockchainTestTxB

FieldTypeLabelDescription
buint64
cuint32

CreateWallet

FieldTypeLabelDescription
pubkeyexonum.PublicKey
namestring

Point

FieldTypeLabelDescription
xuint32
yuint32

TestFixedArrays

FieldTypeLabelDescription
fixed_array_8bytes
fixed_array_16bytes
fixed_array_32bytes

TestProtobufConvert

FieldTypeLabelDescription
keyexonum.PublicKey
hashexonum.Hash
unsigned_32uint32
unsigned_64uint64
regular_i32int32
regular_i64int64
fixed_u32fixed32
fixed_u64fixed64
fixed_i32sfixed32
fixed_i64sfixed64
float_32float
float_64double
booleanbool
s_i32sint32
s_i64sint64
bytes_fieldbytes
string_fieldstring
message_fieldPoint
bit_vecexonum.BitVec
timegoogle.protobuf.Timestamp

TestProtobufConvertMap

FieldTypeLabelDescription
num_mapTestProtobufConvertMap.NumMapEntryrepeated
string_mapTestProtobufConvertMap.StringMapEntryrepeated
bytes_mapTestProtobufConvertMap.BytesMapEntryrepeated
point_mapTestProtobufConvertMap.PointMapEntryrepeated
key_string_mapTestProtobufConvertMap.KeyStringMapEntryrepeated

TestProtobufConvertMap.BytesMapEntry

FieldTypeLabelDescription
keyuint32
valuebytes

TestProtobufConvertMap.KeyStringMapEntry

FieldTypeLabelDescription
keystring
valueuint64

TestProtobufConvertMap.NumMapEntry

FieldTypeLabelDescription
keyuint32
valueuint64

TestProtobufConvertMap.PointMapEntry

FieldTypeLabelDescription
keyuint32
valuePoint

TestProtobufConvertMap.StringMapEntry

FieldTypeLabelDescription
keyuint32
valuestring

TestProtobufConvertRepeated

FieldTypeLabelDescription
keysexonum.PublicKeyrepeated
bytes_arraybytesrepeated
string_arraystringrepeated
num_arrayuint32repeated

TestServiceTx

FieldTypeLabelDescription
valueuint64

TimestampTx

FieldTypeLabelDescription
databytes

Transfer

FieldTypeLabelDescription
fromexonum.PublicKey
toexonum.PublicKey
amountuint64

TxAfterCommit

FieldTypeLabelDescription
heightuint64

TxConfig

FieldTypeLabelDescription
fromexonum.PublicKey
configbytes
actual_fromuint64

TxSimple

FieldTypeLabelDescription
public_keyexonum.PublicKey
msgstring

Top

doc_tests.proto

CreateWallet

FieldTypeLabelDescription
namestring

MyStructBig

FieldTypeLabelDescription
hashexonum.Hash
my_struct_smallMyStructSmall

MyStructSmall

FieldTypeLabelDescription
keyexonum.PublicKey
num_fielduint32
string_fieldstring

MyTransaction

FieldTypeLabelDescription
public_keyexonum.PublicKey

Point

FieldTypeLabelDescription
xint32
yint32

TxA

Transaction fields

TxB

...

Top

helpers.proto

BitVec

FieldTypeLabelDescription
databytes
lenuint64

Hash

FieldTypeLabelDescription
databytes

PublicKey

FieldTypeLabelDescription
databytes

Signature

FieldTypeLabelDescription
databytes

Top

storage.proto

IndexMetadata

FieldTypeLabelDescription
index_typeuint32
is_familybool

Top

protocol.proto

BlockRequest

FieldTypeLabelDescription
toexonum.PublicKey
heightuint64

BlockResponse

FieldTypeLabelDescription
toexonum.PublicKey
blockexonum.Block
precommitsbytesrepeated
transactionsexonum.Hashrepeated

Connect

FieldTypeLabelDescription
pub_addrstring
timegoogle.protobuf.Timestamp
user_agentstring

PeersRequest

FieldTypeLabelDescription
toexonum.PublicKey

PoolTransactionsRequest

FieldTypeLabelDescription
toexonum.PublicKey

Precommit

FieldTypeLabelDescription
validatoruint32
heightuint64
rounduint32
propose_hashexonum.Hash
block_hashexonum.Hash
timegoogle.protobuf.Timestamp

Prevote

FieldTypeLabelDescription
validatoruint32
heightuint64
rounduint32
propose_hashexonum.Hash
locked_rounduint32

PrevotesRequest

FieldTypeLabelDescription
toexonum.PublicKey
heightuint64
rounduint32
propose_hashexonum.Hash
validatorsexonum.BitVec

Propose

FieldTypeLabelDescription
validatoruint32
heightuint64
rounduint32
prev_hashexonum.Hash
transactionsexonum.Hashrepeated

ProposeRequest

FieldTypeLabelDescription
toexonum.PublicKey
heightuint64
propose_hashexonum.Hash

Status

FieldTypeLabelDescription
heightuint64
last_hashexonum.Hash
pool_sizeuint64

TransactionsRequest

FieldTypeLabelDescription
toexonum.PublicKey
txsexonum.Hashrepeated

TransactionsResponse

FieldTypeLabelDescription
toexonum.PublicKey
transactionsbytesrepeated

Top

blockchain.proto

Block

FieldTypeLabelDescription
proposer_iduint32
heightuint64
tx_countuint32
prev_hashHash
tx_hashHash
state_hashHash

ConfigReference

FieldTypeLabelDescription
actual_fromuint64
cfg_hashHash

TransactionResult

FieldTypeLabelDescription
statusuint32
descriptionstring

TxLocation

FieldTypeLabelDescription
block_heightuint64
position_in_blockuint64

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
doubledoubledoublefloat
floatfloatfloatfloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intint
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/long
uint32Uses variable-length encoding.uint32intint/long
uint64Uses variable-length encoding.uint64longint/long
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intint
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/long
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intint
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/long
sfixed32Always four bytes.int32intint
sfixed64Always eight bytes.int64longint/long
boolboolbooleanboolean
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicode
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr

Protos File Tree


.
├── blockchain.proto
├── doc_tests.proto
├── helpers.proto
├── protocol.proto
├── storage.proto
└── tests.proto

0 directories, 6 files

Protobuf sources

src:./tests.proto


// Copyright 2019 The Exonum Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

import "helpers.proto";
import "google/protobuf/timestamp.proto";

package exonum.tests;

message TimestampTx { bytes data = 1; }

message TxAfterCommit { uint64 height = 1; }

message TxConfig {
  exonum.PublicKey from = 1;
  bytes config = 2;
  uint64 actual_from = 3;
}

message TxSimple {
  exonum.PublicKey public_key = 1;
  string msg = 2;
}

message TestServiceTx { uint64 value = 1; }

message BlockchainTestTxA { uint64 a = 1; }

message BlockchainTestTxB {
  uint64 b = 1;
  uint32 c = 2;
}

message CreateWallet {
  exonum.PublicKey pubkey = 1;
  string name = 2;
}

message Transfer {
  exonum.PublicKey from = 1;
  exonum.PublicKey to = 2;
  uint64 amount = 3;
}

message Point {
  uint32 x = 1;
  uint32 y = 2;
}

message TestProtobufConvert {
  exonum.PublicKey key = 1;
  exonum.Hash hash = 2;
  uint32 unsigned_32 = 3;
  uint64 unsigned_64 = 4;
  int32 regular_i32 = 5;
  int64 regular_i64 = 6;
  fixed32 fixed_u32 = 7;
  fixed64 fixed_u64 = 8;
  sfixed32 fixed_i32 = 9;
  sfixed64 fixed_i64 = 10;
  float float_32 = 11;
  double float_64 = 12;
  bool boolean = 13;
  sint32 s_i32 = 14;
  sint64 s_i64 = 15;
  bytes bytes_field = 16;
  string string_field = 17;
  Point message_field = 18;
  exonum.BitVec bit_vec = 19;
  google.protobuf.Timestamp time = 20;
}

message TestProtobufConvertRepeated {
  repeated exonum.PublicKey keys = 1;
  repeated bytes bytes_array = 2;
  repeated string string_array = 3;
  repeated uint32 num_array = 4;
}

message TestProtobufConvertMap {
  map<uint32, uint64> num_map = 1;
  map<uint32, string> string_map = 2;
  map<uint32, bytes> bytes_map = 4;
  map<uint32, Point> point_map = 5;
  map<string, uint64> key_string_map = 6;
}

message TestFixedArrays {
  bytes fixed_array_8 = 1;
  bytes fixed_array_16 = 2;
  bytes fixed_array_32 = 3;
}

src:./doc_tests.proto


// Copyright 2019 The Exonum Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

import "helpers.proto";

package exonum.doc_tests;

message CreateWallet { string name = 1; }

message Point {
  int32 x = 1;
  int32 y = 2;
}

message TxA {
  // Transaction fields
}

message TxB {
  /// ...
}

message MyTransaction { exonum.PublicKey public_key = 1; }

message MyStructSmall {
  exonum.PublicKey key = 1;
  uint32 num_field = 2;
  string string_field = 3;
}
message MyStructBig {
  exonum.Hash hash = 1;
  MyStructSmall my_struct_small = 2;
}

src:./helpers.proto


// Copyright 2019 The Exonum Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package exonum;

message Hash { bytes data = 1; }

message PublicKey { bytes data = 1; }

message Signature { bytes data = 1; }

message BitVec {
  bytes data = 1;
  uint64 len = 2;
}

src:./storage.proto


// Copyright 2019 The Exonum Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package exonum;

message IndexMetadata {
  uint32 index_type = 1;
  bool is_family = 2;
}

src:./protocol.proto


// Copyright 2019 The Exonum Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package exonum.consensus;

import "helpers.proto";
import "blockchain.proto";
import "google/protobuf/timestamp.proto";

message Connect {
  string pub_addr = 1;
  google.protobuf.Timestamp time = 2;
  string user_agent = 3;
}

message Status {
  uint64 height = 1;
  exonum.Hash last_hash = 2;
  uint64 pool_size = 3;
}

message Propose {
  uint32 validator = 1;
  uint64 height = 2;
  uint32 round = 3;
  exonum.Hash prev_hash = 4;
  repeated exonum.Hash transactions = 5;
}

message Prevote {
  uint32 validator = 1;
  uint64 height = 2;
  uint32 round = 3;
  exonum.Hash propose_hash = 4;
  uint32 locked_round = 5;
}

message Precommit {
  uint32 validator = 1;
  uint64 height = 2;
  uint32 round = 3;
  exonum.Hash propose_hash = 4;
  exonum.Hash block_hash = 5;
  google.protobuf.Timestamp time = 6;
}

message BlockResponse {
  exonum.PublicKey to = 1;
  exonum.Block block = 2;
  repeated bytes precommits = 3;
  repeated exonum.Hash transactions = 4;
}

message TransactionsResponse {
  exonum.PublicKey to = 1;
  repeated bytes transactions = 2;
}

message ProposeRequest {
  exonum.PublicKey to = 1;
  uint64 height = 2;
  exonum.Hash propose_hash = 3;
}

message TransactionsRequest {
  exonum.PublicKey to = 1;
  repeated exonum.Hash txs = 2;
}

message PrevotesRequest {
  exonum.PublicKey to = 1;
  uint64 height = 2;
  uint32 round = 3;
  exonum.Hash propose_hash = 4;
  exonum.BitVec validators = 5;
}

message PeersRequest { exonum.PublicKey to = 1; }

message BlockRequest {
  exonum.PublicKey to = 1;
  uint64 height = 2;
}

message PoolTransactionsRequest {
  exonum.PublicKey to = 1;
}

src:./blockchain.proto


// Copyright 2019 The Exonum Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package exonum;

import "helpers.proto";

message Block {
  uint32 proposer_id = 1;
  uint64 height = 2;
  uint32 tx_count = 3;
  exonum.Hash prev_hash = 4;
  exonum.Hash tx_hash = 5;
  exonum.Hash state_hash = 6;
}

message ConfigReference {
  uint64 actual_from = 1;
  exonum.Hash cfg_hash = 2;
}

message TxLocation {
  uint64 block_height = 1;
  uint64 position_in_block = 2;
}

message TransactionResult {
  uint32 status = 1;
  string description = 2;
}