Crate kudu

Crate kudu 

Source
Expand description

This library provides data types and functions to interact with Antelope blockchains.

The basic types can be found in the types module, and the variant type used to represent values handled by Antelope blockchains is AntelopeValue.

On top of each module documentation, the following pages might be of interest:

  • To-Do list: to-do list of items needing to be completed before a first release
  • Notes: list of notes and resources
  • Architecture: overview of the architecture and design decisions

§Feature flags

  • cli: whether to compile the command-line tools alongside the library. This feature is enabled by default and currently installs the kuduconv tool.
  • detailed-error: activate this to enable the with_location macro. If not enabled, the with_location macro will be a no-op.
  • hardened: implement safeguards to check for execution time and recursion depth when validating ABIs. (NOT IMPLEMENTED YET!)
  • float128: add support for a native float128 type. This currently needs a nightly Rust version as f128 support is still experimental. If this is not active, the Float128 will still be available but as a [u8; 16] wrapper.

§Antelope data model

Antelope data model

Data used in the Antelope blockchains can be found in a variety of formats, namely:

  • Rust native data types (structs defined in this library)
  • JSON Value (serde_json::Value) (also called variant in Antelope terminology)
  • JSON string representation
  • binary data

The diagram above shows those types and the different ways to convert between them.

  • most of the conversions are handled via the serde::Serialize and serde::Deserialize traits.
  • to convert between a JSON value and a binary stream you need to use an instance of the ABI class which has been initialized with a data schema (ABIDefinition).
  • to convert between a Rust native value and a binary stream you need to use the ABISerializable trait, which you can automatically derive using the ABISerializable derive macro.

§Traits implemented for native types

Wherever possible, the following traits are implemented for the base types:

§Warnings / pitfalls

  • when defining your own types, if you have a bytes field make sure to use the Bytes type instead of Vec<u8> otherwise the JSON serialization will not be correct.
  • when defining a variant type using a Rust enum, you need to use the SerializeEnum derive macro instead of serde::Serialize and serde::Deserialize. This is because the discriminant needs to be encoded in a specific way which cannot be achieved with the serde::Serialize trait.

§kuduconv CLI tool

The kuduconv tool provides JSON <> hex conversion functionality, similar to what the abieos tools generate_hex_from_json and generate_json_from_hex do.

Example:

$ kuduconv -h  # always nice to read the help to know what a program can do!

$ kuduconv to-hex --abi token.abi transfer {"from": "useraaaaaaaa", "to": "useraaaaaaab", "quantity": "0.0001 SYS", "memo": ""}

§Differences between this library and the Antelope C++ library

  • hex numbers here are lowercase whereas C++ outputs hex data in upper case
  • C++ outputs i64 and u64 as double-quoted, this library doesn’t

Re-exports§

pub use api::APIClient;
pub use abi::ABI;
pub use abi::ABIError;
pub use abi::ABIDefinition;
pub use abi::ABIProvider;
pub use abi::TypeName;
pub use bytestream::ByteStream;
pub use bytestream::StreamError;
pub use abiserializable::ABISerializable;
pub use abiserializable::SerializeError;
pub use abiserializable::to_bin;
pub use abiserializable::to_hex;
pub use abiserializable::from_bin;
pub use types::*;
pub use chain::*;

Modules§

abi
This module provides tools to encode/decode Antelope types into/from an ABI.
abiserializable
api
bytestream
chain
this contains some basic types for the chain FIXME FIXME write me properly!!
config
convert
doc
json
This module provides the same functionality as serde_json but uses a specific formatter for to_string that tries to match the way the the C++ Antelope code outputs JSON.
macros
types
Antelope built-in types and other base types

Macros§

impl_auto_error_conversion
Define the From conversion from an error type to another, where the first is the source of the second. It will use the given Snafu context selector to do so.
json
Construct a serde_json::Value from a JSON literal.

Structs§

JsonError
This type represents all possible errors that can occur when serializing or deserializing JSON data.
JsonMap
Represents a JSON key/value type.

Enums§

JsonValue
Represents any valid JSON value.

Attribute Macros§

contract
Attribute macro to easily declare structs representing contract actions.
with_location
Add a location field to all variants of a Snafu error enum

Derive Macros§

ABISerializable
Implement the ABISerializable trait
SerializeEnum
Implement the serde::Serialize and serde::Deserialize trait
SerializeEnumPrefixed
Implement the serde::Serialize and serde::Deserialize trait