From 8bce3cc008fc14bd23c588c7eb76b2bfbed3ea15 Mon Sep 17 00:00:00 2001 From: Vadim Nabiev Date: Thu, 28 Oct 2021 16:41:54 +0300 Subject: [PATCH] there is added readme.md --- readme.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 readme.md diff --git a/readme.md b/readme.md new file mode 100644 index 00000000..aa022e64 --- /dev/null +++ b/readme.md @@ -0,0 +1,168 @@ +# About +This project provides written in Java API for interaction with a Polkadot or Substrate based network. + +## Key features +- ### Java 8 or higher. +The main idea is to make this library available and usable for as many projects as possible. + +- ### Non-blocking API. + +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<>`. + +- ### Declarative approach. +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: +- [x] Scale + - [x] `@ScaleWriter`; + - [x] `@ScaleReader`; + - [x] `@Scale`; + - [x] `@ScaleGeneric`; + - [x] `@Ignore`; + +- [x] Rpc + - [x] `@RpcInterface`; + - [x] `@RpcCall`; + - [x] `@RpcSubscription`; + - [x] `@RpcEncoder`; + - [x] `@RpcDecoder`; + +- [ ] Pallet + - [ ] `@Pallet`; + - [ ] `@Transaction`; + - [ ] `@Query`; + - [ ] `@EventHandler`. + +These allow the generation of scale serializers, deserializers, RPC methods, code for interaction with pallet, etc. +More examples you can find below. + +- ### Deferred parametrization of codecs +Annotations for codecs allow deferring parameters of a generic until it's used at an RPC method. E.g.: + ```java +@RequiredArgsConstructor +@Getter +@ScaleWriter +public class Some { + private final int number; + private final A some; +} + +@RpcInterface(section = "test") +public interface TestSection { + @RpcCall(method = "sendSome") + CompletableFuture doNothing(@Scale Some 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 value`, it injects the `Strings`'s writer into the writer of `Some`. + +- ### GC Manageable requests. +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. + +- ### Tests run with substrate node. +All API methods related to the substrate node will be tested for operability and compatibility. +Currently we use [test containers](https://www.testcontainers.org/) and docker image [parity/substrate:v3.0.0](https://hub.docker.com/layers/parity/substrate/v3.0.0/images/sha256-1aef07509d757c584320773c476dcb6077578bbf2f5e468ceb413dcf908897f1?context=explore). + +## Our vision of the API +### How to generate scale codec for DTO (implemented) +```java +@RequiredArgsConstructor +@Getter +@ScaleWriter +public class SignedExtra implements Extra, SignedExtension { + @Ignore + private final long specVersion; + @Ignore + private final long txVersion; + @Ignore + private final BlockHash genesis; + @Ignore + private final BlockHash eraBlock; + private final E era; + @Scale(ScaleType.CompactBigInteger.class) + private final BigInteger nonce; + @Scale(ScaleType.CompactBigInteger.class) + private final BigInteger tip; + + @Override + public AdditionalExtra getAdditionalExtra() { + return new SignedAdditionalExtra(specVersion, txVersion, genesis, eraBlock); + } +} +``` + +### How to generate RPC interface (implemented) +```java +@RpcInterface(section = "author") +public interface Author { + @RpcCall(method = "hasKey") + CompletableFuture hasKey(@Scale PublicKey publicKey, String keyType); + + @RpcCall(method = "insertKey") + CompletableFuture insertKey(String keyType, String secretUri, @Scale PublicKey publicKey); + + @RpcCall(method = "submitExtrinsic") + @Scale + CompletableFuture submitExtrinsic(@Scale Extrinsic extrinsic); + + @RpcSubscription(type = "extrinsicUpdate", subscribeMethod = "submitAndWatchExtrinsic", unsubscribeMethod = "unwatchExtrinsic") + CompletableFuture>> submitAndWatchExtrinsic(@Scale Extrinsic extrinsic, + BiConsumer callback); +} +``` + +### Create instance of API (TBD) +```java +Api api = Api.builder() + .useWs() + .withNodes("127.0.0.1:9944", "127.0.0.2:9944") + .scanAnnotatedFrom("com.my_company.first", "com.my_company.second") + .build(); +``` + +### RPC: call method (implemented but not integrated into the API) +```java +CompletableFuture versionFuture = api.getRpc() + .getState() + .getRuntimeVersion(); +``` + +### RPC: subscribe (implemented but not integrated into the API) +```java +CompletableFuture unsubscribe = api.getRpc() + .getChain() + .subscribeNewHeads((ex, header) -> { print(header); }); +``` + +### Pallet: transaction (TBD) +```java +api.pallete(MyPallet.class) + .myExtrinsic(someValue) + .signAndSend(KEY_PAIR); +``` + +## To be implemented +- [x] Transport - layer that interacts with a node. It provides async API for RPC requests. +- [ ] Scale + - [x] Scale codec - implementation of the [SCALE](https://docs.substrate.io/v3/advanced/scale-codec/) for standard types. + - [ ] Support scale for *union* types + - [x] Scale code generation - approach to generate scale encoders/decoders for annotated classes. +- [ ] Signing: + - [x] SR25519 + - [ ] ED25519 +- [x] RPC code generation + - [x] RPC interfaces with methods + - [x] RPC encoders/decoders + - [ ] Declare known RPC sections and methods. +- [ ] Handling metadata +- [ ] Pallet API + - [ ] Transactions + - [ ] Queries + - [ ] Constants + - [ ] Events +- [ ] Load balancing \ No newline at end of file