README
RLP decoder/reader
Currently supports solidity v0.6.0
Please raise issues for bugs, and solidity updates. I will be monitoring the solidity changelogs and updating this package accordingly
Installation
npm install solidity-rlp
in the project directory. Make sure to install through npm for prompt updates!import "solidity-rlp/contracts/RLPReader.sol"
in the desired smart contract.
See the example smart contract below
Usage
The reader contract provides an interface to first take RLP encoded bytes and convert them into
an internal data structure, RLPItem
through the function, toRlpItem(bytes)
. This data structure can then be
destructured into the desired data types.
Transformations (all take an RLPItem as an arg):
isList(RLPItem) bool
: inidicator if the encoded data is a listtoList(RLPItem) RLPItem[]
: returns a list of RLPItemstoBytes(RLPItem) bytes
: returns the payload in bytestoAddress(RLPItem) address
: returns the encoded address. Must be exactly 20 bytes.toUint(RLPItem) uint
: returns the encoded uint. Enforced data is capped to 32 bytes.toUintStrict(RLPItem) uint
: returns the encoded uint. Encoded data must be padded to 32 bytes.toBoolean(RLPItem) bool
: returns the encoded booleantoRlpBytes(RLPItem) bytes
: returns the raw rlp encoded byte formrlpLen(RLPItem) uint
: returns the byte length of the rlp itempayloadLocation(RLPItem) (uint memPtr, uint len)
: returns the memory pointer and byte length of the data payloadpayloadLen(RLPItem) uint
: returns the byte length of the data payload; an alias to payloadLocation(item)[1]
Note: The reader contract only provides only these conversion functions. All other solidity data types can be derived from
this base. For example, a bytes32
encoded data type is equivalent to bytes32(toUint(RLPItem))
. Start with a uint and convert from there.
A string can be retrieved by string(toBytes(RLPItem))
. See example for a sample smart contract.
Iteration functions:
iterator(RLPItem) Iterator
: returns anIterator
over the RLPItem. RLPItem must be an encoded listhasNext(Iterator) bool
: indicator if there is another item to iterate onnext(Iterator) RLPItem
: returns the nextRLPItem
in the iterator
Utility functions:
rlpBytesKeccak256(RLPItem) bytes32
: returns keccak256 hash of RLP encoded bytes. A cheap version ofkeccak256(toRlpBytes(RLPItem))
that avoids copying memory.payloadKeccak256(RLPItem) bytes32
: returns keccak256 hash of the item payload. A cheap version ofkeccak256(toBytes(RLPItem))
that avoids copying memory.
Example
import "solidity-rlp/contracts/RLPReader.sol"
contract SomeContract {
// optional way to attach library functions to these data types.
using RLPReader for RLPReader.RLPItem;
using RLPReader for RLPReader.Iterator;
using RLPReader for bytes;
// lets assume that rlpBytes is an encoding of [[1, "nested"], 2, 0x<Address>]
function someFunctionThatTakesAnEncodedItem(bytes memory rlpBytes) public {
RLPReader.RLPItem[] memory ls = rlpBytes.toRlpItem().toList(); // must convert to an rlpItem first!
RLPReader.RLPItem memory item = ls[0]; // the encoding of [1, "nested"].
item.toList()[0].toUint(); // 1
string(item.toList()[1].toBytes()); // "nested"
ls[1].toUint(); // 2
ls[2].toAddress(); // 0x<Address>
}
// lets assume rlpBytes is an encoding of [["sublist"]]
function someFunctionThatDemonstratesIterators(bytes memory rlpBytes) public {
RLPReader.Iterator memory iter = rlpBytes.toRlpItem().iterator();
RLPReader.Iterator memory subIter = iter.next().iterator();
// iter.hasNext() == false
// string(subIter.next().toBytes()) == "sublist"
// subIter.hasNext() == false
}
}
Tests
git clone https://github.com/hamdiallam/solidity-rlp && cd solidity-rlp
npm install
npm install -g truffle ganache-cli
installed globally for the dev envirnomentganache-cli
run in a background process or seperate terminal window.truffle compile && truffle test