java-rlp

Fast ethereum rlp encode, decode and object mapping in java.

Notes

Supports RLP primitives of boolean, short, int, long, java.math.BigInteger and String.
Supports POJO(Plain Ordinary Java Object) with at least one @RLP annotated field, a no-arguments constructor is required.
Supports container-like interfaces of java.util.Collection, java.util.List, java.util.Set, java.util.Queue, java.util.Deque, java.util.Map, java.util.ConcurrentMap and their no-abstract implementations.
Generic info of fields in POJO class could be nested to arbitrary deepth.
Every value in @RLP of a POJO class should be unique and continous.
String s = null will be encoded as empty string String s = "".
For boolean, true will be encoded as 1 while false will be encoded as 0
null values of Boolean, Byte, Short, Integer, Long and BigInteger will be encoded as 0
null byte array byte[] bytes = null will be encoded as empty byte array byte[] bytes = new byte[0]
transient field will be ignored by default

Notes on java.util.Collection and java.util.Map

Maps will be encoded as key-value pairs RLPList [key1, value1, key2, value2, ...].
java.util.TreeMap is recommended implementation of java.util.Map since key-value pairs in TreeMap are ordered.
java.util.TreeSet is recommended implementation of java.util.Set since keys in TreeSet are ordered.
Besides java.util.TreeMap, the ordering of key-value pairs could be specified by @RLPEncoding.keyOrdering() when encoding.
Besides java.util.TreeSet, the ordering of element of java.util.Set could be specified by @RLPEncoding.keyOrdering() when encoding.
If the ordering of key-value pairs is absent, the encoding of the java.util.Map may not be predictable, encoding of java.util.Set is similar.

Examples

RLP object mapping

package org.tdf.rlp;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.List;

// RLP could encode & decode Tree-like object.
public class Node{
    // declared fields will be encoded with ordering of handwriting
    public String name;

    public List<Node> children;

    // field with @RLPIgnored will be ignored when encoding & decoding
    @RLPIgnored
    public String ignored;

    // if some fields are annotated with @RLP, 
    // fields without @RLP annotation will be ignored
    // the fields above is analogy to
    /**
     * @RLP(0)
     * public String name; 
     * @RLP(1)
     * public List<Node> children;
     * 
     * public String ignored;
    **/
     
    // a no-argument constructor
    public Node() {
    }

    public Node(String name) {
        this.name = name;
    }

    public void addChildren(Collection<Node> nodes){
        if(children == null){
            children = new ArrayList<>();
        }
        if (!nodes.stream().allMatch(x -> x != this)){
            throw new RuntimeException("tree like object cannot add self as children");
        }
        children.addAll(nodes);
    }

    public static void main(String[] args){
        Node root = new Node("1");
        root.addChildren(Arrays.asList(new Node("2"), new Node("3")));
        Node node2 = root.children.get(0);
        node2.addChildren(Arrays.asList(new Node("4"), new Node("5")));
        root.children.get(1).addChildren(Arrays.asList(new Node("6"), new Node("7")));

        // encode to byte array
        byte[] encoded = RLPCodec.encode(root);
        // read as rlp tree
        RLPElement el = RLPElement.readRLPTree(root);
        // decode from byte array
        Node root2 = RLPCodec.decode(encoded, Node.class);
        el = RLPElement.fromEncoded(encoded);
        // decode from rlp element
        root2 = el.as(Node.class);
        root2 = RLPCodec.decode(el, Node.class);
    }

    public static void assertTrue(boolean b){
        if(!b) throw new RuntimeException("assertion failed");
    }
}

RLP encode & decode of POJO with tree-like field.

public static class Tree{
    @RLPDecoding(as = ConcurrentHashMap.class) 
    /* The decoded type will be java.util.concurrent.ConcurrentHashMap 
    instead of java.util.HashMap which is the default implementation of java.util.Map. */ 
    public Map<Map<String, Set<String>>, byte[]> tree;

    // although ByteArrayMap in ethereumJ is not supported by default, you can enable it by annotation
    @RLPDecoding(as = ByteArrayMap.class)
    public Map<byte[], String> stringMap;
}

public class Main{
    public static void main(String[] args){
        Tree tree = new Tree();
        tree.tree = new HashMap<>();
        Map<String, Set<String>> map = new HashMap<>();
        map.put("1", new HashSet<>(Arrays.asList("1", "2", "3")));
        tree.tree.put(map, "1".getBytes());
        byte[] encoded = RLPCodec.encode(tree);
        RLPElement el = RLPElement.fromEncoded(encoded, false);
        Tree tree1 = RLPCodec.decode(encoded, Tree.class);
        assert tree1.tree instanceof ConcurrentHashMap;
        Map<String, Set<String>> tree2 = tree1.tree.keySet().stream()
                .findFirst().get();
        assert Arrays.equals(tree1.tree.get(tree2), "1".getBytes());
        assert tree2.get("1").containsAll(Arrays.asList("1", "2", "3"));
    }
}

Tree-like type encode & decode without wrapper class.

public class Main{
    // store generic info in a dummy field
    private abstract class Dummy2 {
        private List<Map<String, String>> dummy;
    }

    public static void main(String[] args) throws Exception{
        List<Map<String, String>> list = new ArrayList<>();
        list.add(new HashMap<>());
        list.get(0).put("1", "1");

        List<Map<String, String>> decoded = (List<Map<String, String>>) RLPCodec.decodeContainer(
                RLPCodec.encode(list),
                Container.fromField(Dummy2.class.getDeclaredField("dummy"))
        );

        assert decoded.get(0).get("1").equals("1");
    }
}

Custom encode & decode configured by @RLPEncoding and @RLPDecoding.

package org.tdf.rlp;

import java.util.HashMap;
import java.util.Map;

public class Main{
    public static class MapEncoderDecoder implements RLPEncoder<Map<String, String>>, RLPDecoder<Map<String, String>> {
        @Override
        public Map<String, String> decode(RLPElement list) {
            Map<String, String> map = new HashMap<>(list.size() / 2);
            for (int i = 0; i < list.size(); i += 2) {
                map.put(list.get(i).asString(), list.get(i+1).asString());
            }
            return map;
        }

        @Override
        public RLPElement encode(Map<String, String> o) {
            RLPList list = RLPList.createEmpty(o.size() * 2);
            o.keySet().stream().sorted(String::compareTo).forEach(x -> {
                list.add(RLPItem.fromString(x));
                list.add(RLPItem.fromString(o.get(x)));
            });
            return list;
        }
    }

    public static class MapWrapper{
        @RLP
        @RLPEncoding(MapEncoderDecoder.class)
        @RLPDecoding(MapEncoderDecoder.class)
        public Map<String, String> map;

        public MapWrapper(Map<String, String> map) {
            this.map = map;
        }

        public MapWrapper() {
        }
    }

    public static void main(String[] args){
        Map<String, String> m = new HashMap<>();
        m.put("a", "1");
        m.put("b", "2");
        byte[] encoded = RLPCodec.encode(new MapWrapper(m));
        MapWrapper decoded = RLPCodec.decode(encoded, MapWrapper.class);
        assertTrue(decoded.map.get("a").equals("1"));
    }

    public static void assertTrue(boolean b){
        if(!b) throw new RuntimeException("assertion failed");
    }
}

Add global context to avoid duplicated @RLPEncoding and @RLPDecoding

public class Main{
    public static class LocalDateDecoder implements RLPDecoder<LocalDate> {
        @Override
        public LocalDate decode(RLPElement rlpElement) {
            if(rlpElement.isNull()) return null;
            int[] data = rlpElement.as(int[].class);
            return LocalDate.of(data[0], data[1], data[2]);
        }
    }

    public class LocalDateEncoder implements RLPEncoder<LocalDate> {
        @Override
        public RLPElement encode(LocalDate localDate) {
            return RLPElement.readRLPTree(
                    new int[]{localDate.getYear(), localDate.getMonthValue(), localDate.getDayOfMonth()}
            );
        }
    }

    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public static class User{
        private LocalDate birthDay;
    }

    public static void main(String[] args){
        RLPContext context = RLPContext
                .newInstance()
                .withDecoder(LocalDate.class, new LocalDateDecoder())
                .withEncoder(LocalDate.class, new LocalDateEncoder());
        RLPMapper mapper = new RLPMapper().withContext(context);
        User u = new User();
        element = mapper.readRLPTree(u);
        User decoded = mapper.decode(element, User.class);
        assert decoded.birthDay == null;

        u.birthDay = LocalDate.now();
        byte[] encoded = mapper.encode(u);
        decoded = mapper.decode(encoded, User.class);
        System.out.println(decoded.birthDay.format(DateTimeFormatter.ISO_DATE));    
    }

}

Encode & Decode containers

public class Main {
    public static interface SomeMap extends Map<String, String>{

    }

    public static final Container CONTAINER = Container.fromType(SomeMap.class.getGenericInterfaces()[0]);


    public static void main(String[] args){
        byte[] bytes = new byte[0];
        Map<String, String> m  = (Map<String, String>) RLPCodec.decodeContainer(bytes, CONTAINER);
    }
}

Benchmark

see RLPTest.performanceDecode for benchmark

Benchmark compare to EthereumJ:

Platform:

Motherborad: B450M
CPU: Ryzen 3700x, 8 core, 16 threads
Memory: (16GB x 2) DDR4 3200hz

decoding list 10000000 times:

ethereumJ: 3698ms our: 2515ms

TrustedDataFramework/java-rlp

java-rlp

Notes

Notes on java.util.Collection and java.util.Map

Examples

Benchmark