|
1 | 1 | // Copyright (c) 2025 IOTA Stiftung |
2 | 2 | // SPDX-License-Identifier: Apache-2.0 |
3 | 3 |
|
4 | | -//! Core type definitions for the IOTA blockchain. |
5 | | -//! |
6 | | -//! [IOTA] is a next-generation smart contract platform with high throughput, |
7 | | -//! low latency, and an asset-oriented programming model powered by the Move |
8 | | -//! programming language. This crate provides type definitions for working with |
9 | | -//! the data that makes up the IOTA blockchain. |
10 | | -//! |
11 | | -//! [IOTA]: https://iota.org |
12 | | -//! |
13 | | -//! # Feature flags |
14 | | -//! |
15 | | -//! This library uses a set of [feature flags] to reduce the number of |
16 | | -//! dependencies and amount of compiled code. By default, no features are |
17 | | -//! enabled which allows one to enable a subset specifically for their use case. |
18 | | -//! Below is a list of the available feature flags. |
19 | | -//! |
20 | | -//! - `schemars`: Enables JSON schema generation using the [schemars] library. |
21 | | -//! - `serde`: Enables support for serializing and deserializing types to/from |
22 | | -//! BCS utilizing [serde] library. |
23 | | -//! - `rand`: Enables support for generating random instances of a number of |
24 | | -//! types via the [rand] library. |
25 | | -//! - `hash`: Enables support for hashing, which is required for deriving |
26 | | -//! addresses and calculating digests for various types. |
27 | | -//! - `proptest`: Enables support for the [proptest] library by providing |
28 | | -//! implementations of [proptest::arbitrary::Arbitrary] for many types. |
29 | | -//! |
30 | | -//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section |
31 | | -//! [serde]: https://docs.rs/serde |
32 | | -//! [rand]: https://docs.rs/rand |
33 | | -//! [proptest]: https://docs.rs/proptest |
34 | | -//! [schemars]: https://docs.rs/schemars |
35 | | -//! [proptest::arbitrary::Arbitrary]: https://docs.rs/proptest/latest/proptest/arbitrary/trait.Arbitrary.html |
36 | | -//! |
37 | | -//! # BCS |
38 | | -//! |
39 | | -//! [BCS] is the serialization format used to represent the state of the |
40 | | -//! blockchain and is used extensively throughout the IOTA ecosystem. In |
41 | | -//! particular the BCS format is leveraged because it _"guarantees canonical |
42 | | -//! serialization, meaning that for any given data type, there is a one-to-one |
43 | | -//! correspondence between in-memory values and valid byte representations."_ |
44 | | -//! One benefit of this property of having a canonical serialized representation |
45 | | -//! is to allow different entities in the ecosystem to all agree on how a |
46 | | -//! particular type should be interpreted and more importantly define a |
47 | | -//! deterministic representation for hashing and signing. |
48 | | -//! |
49 | | -//! This library strives to guarantee that the types defined are fully |
50 | | -//! BCS-compatible with the data that the network produces. The one caveat to |
51 | | -//! this would be that as the IOTA protocol evolves, new type variants are added |
52 | | -//! and older versions of this library may not support those newly |
53 | | -//! added variants. The expectation is that the most recent release of this |
54 | | -//! library will support new variants and types as they are released to IOTA's |
55 | | -//! `testnet` network. |
56 | | -//! |
57 | | -//! See the documentation for the various types defined by this crate for a |
58 | | -//! specification of their BCS serialized representation which will be defined |
59 | | -//! using ABNF notation as described by [RFC-5234]. In addition to the format |
60 | | -//! itself, some types have an extra layer of verification and may impose |
61 | | -//! additional restrictions on valid byte representations above and beyond those |
62 | | -//! already provided by BCS. In these instances the documentation for those |
63 | | -//! types will clearly specify these additional restrictions. |
64 | | -//! |
65 | | -//! Here are some common rules: |
66 | | -//! |
67 | | -//! ```text |
68 | | -//! ; --- BCS Value --- |
69 | | -//! bcs-value = bcs-struct / bcs-enum / bcs-length-prefixed / bcs-fixed-length |
70 | | -//! bcs-length-prefixed = bytes / string / vector / option |
71 | | -//! bcs-fixed-length = u8 / u16 / u32 / u64 / u128 / |
72 | | -//! i8 / i16 / i32 / i64 / i128 / |
73 | | -//! boolean |
74 | | -//! bcs-struct = *bcs-value ; Sequence of serialized fields |
75 | | -//! bcs-enum = uleb128-index bcs-value ; Enum index and associated value |
76 | | -//! |
77 | | -//! ; --- Length-prefixed types --- |
78 | | -//! bytes = uleb128 *OCTET ; Raw bytes of the specified length |
79 | | -//! string = uleb128 *OCTET ; valid utf8 string of the specified length |
80 | | -//! vector = uleb128 *bcs-value ; Length-prefixed list of values |
81 | | -//! option = %x00 / (%x01 bcs-value) ; optional value |
82 | | -//! |
83 | | -//! ; --- Fixed-length types --- |
84 | | -//! u8 = OCTET ; 1-byte unsigned integer |
85 | | -//! u16 = 2OCTET ; 2-byte unsigned integer, little-endian |
86 | | -//! u32 = 4OCTET ; 4-byte unsigned integer, little-endian |
87 | | -//! u64 = 8OCTET ; 8-byte unsigned integer, little-endian |
88 | | -//! u128 = 16OCTET ; 16-byte unsigned integer, little-endian |
89 | | -//! i8 = OCTET ; 1-byte signed integer |
90 | | -//! i16 = 2OCTET ; 2-byte signed integer, little-endian |
91 | | -//! i32 = 4OCTET ; 4-byte signed integer, little-endian |
92 | | -//! i64 = 8OCTET ; 8-byte signed integer, little-endian |
93 | | -//! i128 = 16OCTET ; 16-byte signed integer, little-endian |
94 | | -//! boolean = %x00 / %x01 ; Boolean: 0 = false, 1 = true |
95 | | -//! array = *(bcs-value) ; Fixed-length array |
96 | | -//! |
97 | | -//! ; --- ULEB128 definition --- |
98 | | -//! uleb128 = 1*5uleb128-byte ; Variable-length ULEB128 encoding |
99 | | -//! uleb128-byte = %x00-7F / %x80-FF ; ULEB128 continuation rules |
100 | | -//! uleb128-index = uleb128 ; ULEB128-encoded variant index |
101 | | -//! ``` |
102 | | -//! |
103 | | -//! [BCS]: https://docs.rs/bcs |
104 | | -//! [RFC-5234]: https://datatracker.ietf.org/doc/html/rfc5234 |
105 | | -
|
106 | 4 | #![expect(unused)] |
107 | | -#![allow(clippy::wrong_self_convention)] |
| 5 | +#![allow( |
| 6 | + clippy::wrong_self_convention, |
| 7 | + clippy::should_implement_trait, |
| 8 | + clippy::new_without_default |
| 9 | +)] |
108 | 10 |
|
109 | 11 | use base64ct::Encoding; |
110 | 12 |
|
111 | | -mod crypto; |
112 | | -mod error; |
113 | | -mod faucet; |
114 | | -mod graphql; |
115 | | -mod transaction_builder; |
116 | | -mod types; |
117 | | -mod uniffi_helpers; |
| 13 | +pub mod crypto; |
| 14 | +pub mod error; |
| 15 | +pub mod faucet; |
| 16 | +pub mod graphql; |
| 17 | +pub mod transaction_builder; |
| 18 | +pub mod types; |
| 19 | +pub mod uniffi_helpers; |
118 | 20 |
|
119 | 21 | uniffi::setup_scaffolding!(); |
120 | 22 |
|
|
0 commit comments