This project provides written in Java API for interaction with a Polkadot or Substrate based network.
The main idea is to make this library available and usable for as many projects as possible.
The API is designed to be non-blocking in order to not engage resources for waiting responses from a node, especially when working with web sockets.
Each method returns CompletableFuture<>.
Some of our goals are:
- make API simpler for usage;
- let users organize their code similar to the one in the pallet they are interacting with;
- hide difficulties of low level and infrastructure code;
- facilitate the future maintenance.
The best approach to reach project’s goals is to use annotations and code generation techniques. Below are listed some annotations that this API shall provide:
-
Scale
-
@ScaleWriter; -
@ScaleReader; -
@Scale; -
@ScaleGeneric; -
@Ignore;
-
-
Rpc
-
@RpcInterface; -
@RpcCall; -
@RpcSubscription; -
@RpcEncoder; -
@RpcDecoder;
-
-
Pallet
-
@Pallet; -
@Transaction; -
@Storage; -
@EventHandler.
-
These allow the generation of scale serializers, deserializers, RPC methods, code for interaction with pallet, etc. More examples you can find below.
Annotations for codecs allow deferring parameters of a generic until it's used at an RPC method. E.g.:
@RequiredArgsConstructor
@Getter
@ScaleWriter
public class Some<A> {
private final int number;
private final A some;
}
@RpcInterface(section = "test")
public interface TestSection {
@RpcCall(method = "sendSome")
CompletableFuture<Boolean> doNothing(@Scale Some<Parameter> value);
}Annotation processors will generate scale writer for the class Some which expects another writer as a dependency.
When a processor faces a parameter like Some<String> value, it injects the Strings's writer into the writer of Some.
We take care of either lost responses or canceled futures by not holding handlers that are needed to match an RPC request with a response.
All API methods related to the substrate node will be tested for operability and compatibility. Currently we use test containers and docker image parity/substrate:v3.0.0.