Crate soroban_env_host::xdr
Expand description
Library and CLI containing types and functionality for working with Stellar XDR.
Types are generated from XDR definitions hosted at stellar/stellar-xdr using xdrgen.
This repository contains code that is in early development, incomplete, not tested, and not recommended for use. The API is unstable, experimental, and is receiving breaking changes frequently.
Usage
Library
To use the library, include in your toml:
stellar-xdr = { version = "...", default-features = true, features = [] }
Features
The crate has several features, tiers of functionality, ancillary functionality, and channels of XDR.
Default features: std, curr.
Teirs of functionality:
std– The std feature provides all functionality (types, encode, decode), and is the default feature set.alloc– The alloc feature usesBoxandVectypes for recursive references and arrays, and is automatically enabled if the std feature is enabled. The default global allocator is used. Support for a custom allocator will be added in #39. No encode or decode capability exists, only types. Encode and decode capability will be added in #46.- If std or alloc are not enabled recursive and array types requires static lifetime values. No encode or decode capability exists. Encode and decode capability will be added in #47.
Ancillary functionality:
base64– Enables support for base64 encoding and decoding.serde– Enables support for serializing and deserializing types with the serde crate.arbitrary– Enables support for interop with the arbitrary crate.
Channels of XDR:
curr– XDR types built from thestellar/stellar-xdrcurrbranch.next– XDR types built from thestellar/stellar-xdrnextbranch.
If a single channel is enabled the types are available at the root of the crate. If multiple channels are enabled they are available in modules at the root of the crate.
CLI
To use the CLI:
cargo install --locked stellar-xdr --version ... --features cli
Examples
Parse a TransactionEnvelope:
stellar-xdr decode --type TransactionEnvelope << -
AAAAA...
-
Parse a ScSpecEntry stream from a contract:
stellar-xdr +next decode --type ScSpecEntry --input stream-base64 --output json-formatted << -
AAAAA...
-
Parse a BucketEntry framed stream from a bucket file:
stellar-xdr decode --type BucketEntry --input stream-framed --output json-formatted bucket.xdr
Modules
Structs
DepthLimitedReadwraps aReadobject and enforces a depth limit to recursive read operations. It maintains adepth_remainingstate tracking remaining allowed recursion depth.DepthLimitedWritewraps aWriteobject and enforces a depth limit to recursive write operations. It maintains adepth_remainingstate tracking remaining allowed recursion depth.
Enums
- Error contains all errors returned by functions in this crate. It can be compared via
PartialEq, however any contained IO errors will only be compared on theirErrorKind.
Constants
- Defines the maximum depth for recursive calls in
Read/WriteXdrto prevent stack overflow. XDR_FILES_SHA256is a list of pairs of source files and their SHA256 hashes.
Traits
DepthLimiteris a trait designed for managing the depth of recursive operations. It provides a mechanism to limit recursion depth, and defines the behavior upon entering and leaving a recursion level.- Discriminant defines types that may contain a one-of value determined according to the discriminant, and exposes the value of the discriminant for that type, such as in an XDR union.
- Name defines types that assign a static name to their value, such as the name given to an identifier in an XDR enum, or the name given to the case in a union.
- Iter defines types that have variants that can be iterated.