2016-01-29 13:59:29 +01:00
|
|
|
//! Common RLP traits
|
2016-01-27 12:14:57 +01:00
|
|
|
use std::ops::Deref;
|
2016-01-29 13:59:29 +01:00
|
|
|
use rlp::bytes::VecLike;
|
2015-12-26 15:48:41 +01:00
|
|
|
use rlp::{DecoderError, UntrustedRlp};
|
2016-01-29 13:59:29 +01:00
|
|
|
use rlp::rlpstream::RlpStream;
|
2016-01-27 12:14:57 +01:00
|
|
|
use elastic_array::ElasticArray1024;
|
|
|
|
use hash::H256;
|
|
|
|
use sha3::*;
|
2015-12-08 00:07:07 +01:00
|
|
|
|
2016-02-03 14:51:45 +01:00
|
|
|
/// Type is able to decode RLP.
|
2015-12-14 12:03:48 +01:00
|
|
|
pub trait Decoder: Sized {
|
2016-02-03 14:51:45 +01:00
|
|
|
/// Read a value from the RLP into a given type.
|
2015-12-08 00:07:07 +01:00
|
|
|
fn read_value<T, F>(&self, f: F) -> Result<T, DecoderError>
|
|
|
|
where F: FnOnce(&[u8]) -> Result<T, DecoderError>;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
2016-02-03 14:51:45 +01:00
|
|
|
/// Get underlying `UntrustedRLP` object.
|
2016-01-19 12:14:29 +01:00
|
|
|
fn as_rlp(&self) -> &UntrustedRlp;
|
2016-02-03 14:51:45 +01:00
|
|
|
/// Get underlying raw bytes slice.
|
2016-01-07 23:59:50 +01:00
|
|
|
fn as_raw(&self) -> &[u8];
|
2015-12-07 23:47:26 +01:00
|
|
|
}
|
|
|
|
|
2016-01-29 13:59:29 +01:00
|
|
|
/// RLP decodable trait
|
2015-12-07 23:47:26 +01:00
|
|
|
pub trait Decodable: Sized {
|
2016-01-29 13:59:29 +01:00
|
|
|
/// Decode a value from RLP bytes
|
|
|
|
fn decode<D>(decoder: &D) -> Result<Self, DecoderError> where D: Decoder;
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Internal helper trait. Implement `Decodable` for custom types.
|
|
|
|
pub trait RlpDecodable: Sized {
|
|
|
|
/// Decode a value from RLP bytes
|
2015-12-08 00:27:12 +01:00
|
|
|
fn decode<D>(decoder: &D) -> Result<Self, DecoderError> where D: Decoder;
|
2015-12-07 23:47:26 +01:00
|
|
|
}
|
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// A view into RLP encoded data
|
2015-12-07 23:47:26 +01:00
|
|
|
pub trait View<'a, 'view>: Sized {
|
2016-02-03 16:43:48 +01:00
|
|
|
/// RLP prototype type
|
2015-12-07 16:32:06 +01:00
|
|
|
type Prototype;
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Payload info type
|
2015-12-07 16:32:06 +01:00
|
|
|
type PayloadInfo;
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Data type
|
2015-12-07 16:32:06 +01:00
|
|
|
type Data;
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Item type
|
2015-12-07 16:32:06 +01:00
|
|
|
type Item;
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Iterator type
|
2015-12-07 23:47:26 +01:00
|
|
|
type Iter;
|
2015-12-07 16:32:06 +01:00
|
|
|
|
2015-12-07 23:47:26 +01:00
|
|
|
/// Creates a new instance of `Rlp` reader
|
2015-12-07 16:32:06 +01:00
|
|
|
fn new(bytes: &'a [u8]) -> Self;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// The raw data of the RLP.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g'];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
2016-01-08 15:52:43 +01:00
|
|
|
/// let dog = rlp.at(1).as_raw();
|
2015-12-07 23:47:26 +01:00
|
|
|
/// assert_eq!(dog, &[0x83, b'd', b'o', b'g']);
|
|
|
|
/// }
|
|
|
|
/// ```
|
2016-01-08 15:52:43 +01:00
|
|
|
fn as_raw(&'view self) -> &'a [u8];
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// Get the prototype of the RLP.
|
2015-12-07 16:32:06 +01:00
|
|
|
fn prototype(&self) -> Self::Prototype;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Get payload info.
|
2015-12-07 16:32:06 +01:00
|
|
|
fn payload_info(&self) -> Self::PayloadInfo;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Get underlieing data.
|
2015-12-07 16:32:06 +01:00
|
|
|
fn data(&'view self) -> Self::Data;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// Returns number of RLP items.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g'];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
|
|
|
/// assert_eq!(rlp.item_count(), 2);
|
|
|
|
/// let view = rlp.at(1);
|
|
|
|
/// assert_eq!(view.item_count(), 0);
|
|
|
|
/// }
|
|
|
|
/// ```
|
2015-12-07 16:32:06 +01:00
|
|
|
fn item_count(&self) -> usize;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// Returns the number of bytes in the data, or zero if it isn't data.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g'];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
|
|
|
/// assert_eq!(rlp.size(), 0);
|
|
|
|
/// let view = rlp.at(1);
|
|
|
|
/// assert_eq!(view.size(), 3);
|
|
|
|
/// }
|
|
|
|
/// ```
|
2015-12-07 16:32:06 +01:00
|
|
|
fn size(&self) -> usize;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// Get view onto RLP-slice at index.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// Caches offset to given index, so access to successive
|
|
|
|
/// slices is faster.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g'];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
2015-12-08 12:40:11 +01:00
|
|
|
/// let dog: String = rlp.at(1).as_val();
|
2015-12-07 23:47:26 +01:00
|
|
|
/// assert_eq!(dog, "dog".to_string());
|
|
|
|
/// }
|
2015-12-07 16:32:06 +01:00
|
|
|
fn at(&'view self, index: usize) -> Self::Item;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// No value
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
|
|
|
/// assert!(rlp.is_null());
|
|
|
|
/// }
|
|
|
|
/// ```
|
2015-12-07 16:32:06 +01:00
|
|
|
fn is_null(&self) -> bool;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// Contains a zero-length string or zero-length list.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc0];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
|
|
|
/// assert!(rlp.is_empty());
|
|
|
|
/// }
|
|
|
|
/// ```
|
2015-12-07 16:32:06 +01:00
|
|
|
fn is_empty(&self) -> bool;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// List value
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g'];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
|
|
|
/// assert!(rlp.is_list());
|
|
|
|
/// }
|
|
|
|
/// ```
|
2015-12-07 16:32:06 +01:00
|
|
|
fn is_list(&self) -> bool;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// String value
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g'];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
|
|
|
/// assert!(rlp.at(1).is_data());
|
|
|
|
/// }
|
|
|
|
/// ```
|
2015-12-07 16:32:06 +01:00
|
|
|
fn is_data(&self) -> bool;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// Int value
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc1, 0x10];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
|
|
|
/// assert_eq!(rlp.is_int(), false);
|
|
|
|
/// assert_eq!(rlp.at(0).is_int(), true);
|
|
|
|
/// }
|
|
|
|
/// ```
|
2015-12-07 16:32:06 +01:00
|
|
|
fn is_int(&self) -> bool;
|
2015-12-07 23:47:26 +01:00
|
|
|
|
|
|
|
/// Get iterator over rlp-slices
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-07 23:47:26 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let data = vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g'];
|
|
|
|
/// let rlp = Rlp::new(&data);
|
2015-12-08 12:40:11 +01:00
|
|
|
/// let strings: Vec<String> = rlp.iter().map(| i | i.as_val()).collect();
|
2015-12-07 23:47:26 +01:00
|
|
|
/// }
|
|
|
|
/// ```
|
|
|
|
fn iter(&'view self) -> Self::Iter;
|
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Decode data into an object
|
2016-01-29 13:59:29 +01:00
|
|
|
fn as_val<T>(&self) -> Result<T, DecoderError> where T: RlpDecodable;
|
2015-12-08 14:44:22 +01:00
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Decode data at given list index into an object
|
2016-01-29 13:59:29 +01:00
|
|
|
fn val_at<T>(&self, index: usize) -> Result<T, DecoderError> where T: RlpDecodable;
|
2015-12-07 23:47:26 +01:00
|
|
|
}
|
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Raw RLP encoder
|
2015-12-07 23:47:26 +01:00
|
|
|
pub trait Encoder {
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Write a value represented as bytes
|
2016-01-27 12:14:57 +01:00
|
|
|
fn emit_value<E: ByteEncodable>(&mut self, value: &E);
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Write raw preencoded data to the output
|
2016-01-07 23:59:50 +01:00
|
|
|
fn emit_raw(&mut self, bytes: &[u8]) -> ();
|
2015-12-07 23:47:26 +01:00
|
|
|
}
|
|
|
|
|
2016-01-27 12:14:57 +01:00
|
|
|
/// Primitive data type encodable to RLP
|
|
|
|
pub trait ByteEncodable {
|
|
|
|
/// Serialize this object to given byte container
|
|
|
|
fn to_bytes<V: VecLike<u8>>(&self, out: &mut V);
|
|
|
|
/// Get size of serialised data in bytes
|
|
|
|
fn bytes_len(&self) -> usize;
|
|
|
|
}
|
|
|
|
|
2016-01-28 20:13:05 +01:00
|
|
|
/// Structure encodable to RLP. Implement this trait for
|
2015-12-07 23:47:26 +01:00
|
|
|
pub trait Encodable {
|
2016-01-27 12:14:57 +01:00
|
|
|
/// Append a value to the stream
|
|
|
|
fn rlp_append(&self, s: &mut RlpStream);
|
|
|
|
|
|
|
|
/// Get rlp-encoded bytes for this instance
|
|
|
|
fn rlp_bytes(&self) -> ElasticArray1024<u8> {
|
|
|
|
let mut s = RlpStream::new();
|
|
|
|
self.rlp_append(&mut s);
|
|
|
|
s.drain()
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Get the hash or RLP encoded representation
|
|
|
|
fn rlp_sha3(&self) -> H256 { self.rlp_bytes().deref().sha3() }
|
2015-12-07 16:32:06 +01:00
|
|
|
}
|
|
|
|
|
2016-01-28 20:13:05 +01:00
|
|
|
/// Encodable wrapper trait required to handle special case of encoding a &[u8] as string and not as list
|
|
|
|
pub trait RlpEncodable {
|
|
|
|
/// Append a value to the stream
|
|
|
|
fn rlp_append(&self, s: &mut RlpStream);
|
|
|
|
}
|
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// RLP encoding stream
|
2015-12-07 23:47:26 +01:00
|
|
|
pub trait Stream: Sized {
|
2015-12-08 12:33:05 +01:00
|
|
|
|
|
|
|
/// Initializes instance of empty `Stream`.
|
2015-12-07 23:47:26 +01:00
|
|
|
fn new() -> Self;
|
2015-12-08 12:33:05 +01:00
|
|
|
|
|
|
|
/// Initializes the `Stream` as a list.
|
2015-12-07 23:47:26 +01:00
|
|
|
fn new_list(len: usize) -> Self;
|
2015-12-08 12:33:05 +01:00
|
|
|
|
|
|
|
/// Apends value to the end of stream, chainable.
|
|
|
|
///
|
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-08 12:33:05 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let mut stream = RlpStream::new_list(2);
|
|
|
|
/// stream.append(&"cat").append(&"dog");
|
|
|
|
/// let out = stream.out();
|
|
|
|
/// assert_eq!(out, vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g']);
|
|
|
|
/// }
|
|
|
|
/// ```
|
2016-01-28 20:13:05 +01:00
|
|
|
fn append<'a, E>(&'a mut self, value: &E) -> &'a mut Self where E: RlpEncodable;
|
2015-12-08 12:33:05 +01:00
|
|
|
|
|
|
|
/// Declare appending the list of given size, chainable.
|
|
|
|
///
|
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-08 12:33:05 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let mut stream = RlpStream::new_list(2);
|
2016-01-27 12:14:57 +01:00
|
|
|
/// stream.begin_list(2).append(&"cat").append(&"dog");
|
2015-12-26 15:48:41 +01:00
|
|
|
/// stream.append(&"");
|
2015-12-08 12:33:05 +01:00
|
|
|
/// let out = stream.out();
|
|
|
|
/// assert_eq!(out, vec![0xca, 0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g', 0x80]);
|
|
|
|
/// }
|
|
|
|
/// ```
|
2016-01-27 12:14:57 +01:00
|
|
|
fn begin_list(&mut self, len: usize) -> &mut Self;
|
|
|
|
|
2015-12-08 12:33:05 +01:00
|
|
|
/// Apends null to the end of stream, chainable.
|
|
|
|
///
|
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-08 12:33:05 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let mut stream = RlpStream::new_list(2);
|
|
|
|
/// stream.append_empty_data().append_empty_data();
|
|
|
|
/// let out = stream.out();
|
|
|
|
/// assert_eq!(out, vec![0xc2, 0x80, 0x80]);
|
|
|
|
/// }
|
|
|
|
/// ```
|
2016-01-19 12:14:29 +01:00
|
|
|
fn append_empty_data(&mut self) -> &mut Self;
|
2015-12-08 12:33:05 +01:00
|
|
|
|
|
|
|
/// Appends raw (pre-serialised) RLP data. Use with caution. Chainable.
|
|
|
|
fn append_raw<'a>(&'a mut self, bytes: &[u8], item_count: usize) -> &'a mut Self;
|
|
|
|
|
|
|
|
/// Clear the output stream so far.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-08 12:33:05 +01:00
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-08 12:33:05 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let mut stream = RlpStream::new_list(3);
|
|
|
|
/// stream.append(&"cat");
|
|
|
|
/// stream.clear();
|
|
|
|
/// stream.append(&"dog");
|
|
|
|
/// let out = stream.out();
|
|
|
|
/// assert_eq!(out, vec![0x83, b'd', b'o', b'g']);
|
|
|
|
/// }
|
|
|
|
fn clear(&mut self);
|
|
|
|
|
|
|
|
/// Returns true if stream doesnt expect any more items.
|
|
|
|
///
|
|
|
|
/// ```rust
|
|
|
|
/// extern crate ethcore_util as util;
|
|
|
|
/// use util::rlp::*;
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-08 12:33:05 +01:00
|
|
|
/// fn main () {
|
|
|
|
/// let mut stream = RlpStream::new_list(2);
|
|
|
|
/// stream.append(&"cat");
|
|
|
|
/// assert_eq!(stream.is_finished(), false);
|
|
|
|
/// stream.append(&"dog");
|
|
|
|
/// assert_eq!(stream.is_finished(), true);
|
|
|
|
/// let out = stream.out();
|
|
|
|
/// assert_eq!(out, vec![0xc8, 0x83, b'c', b'a', b't', 0x83, b'd', b'o', b'g']);
|
|
|
|
/// }
|
|
|
|
fn is_finished(&self) -> bool;
|
|
|
|
|
2016-02-03 16:43:48 +01:00
|
|
|
/// Get raw encoded bytes
|
2016-01-08 15:57:50 +01:00
|
|
|
fn as_raw(&self) -> &[u8];
|
2015-12-12 15:57:08 +01:00
|
|
|
|
2015-12-08 12:33:05 +01:00
|
|
|
/// Streams out encoded bytes.
|
2015-12-26 15:48:41 +01:00
|
|
|
///
|
2015-12-08 12:33:05 +01:00
|
|
|
/// panic! if stream is not finished.
|
|
|
|
fn out(self) -> Vec<u8>;
|
2015-12-07 16:32:06 +01:00
|
|
|
}
|