One of the key objectives we had when building the first group of SDKs was to enable developers to change quickly between programming languages without having to adapt to a completely different design. This document intends to guide developers to ship Symbol-based SDKs that share the same design to achieve interoperability.
This package includes the generated API client and DTOs. The HTTP requests are made following the Repository Pattern, and they return Symbol domain immutable models via the Observable Pattern.
The Symbol domain models are immutable by definition, meaning that the developer cannot change their attributes. Instead, the developers have to create new Transactions and dispatch them to the blockchain via TransactionHTTP.
Common operations that require combining multiple REST API requests.
The Symbol SDK uses the ReactiveX Library intensely.
The benefits of using a reactive approach are:
If you are new to Reactive Programming, we encourage you to start with the online guide Learn RxJS.
Create a new repository, preferably on GitHub, with:
A project with good test coverage it’s more likely to be used and trusted by the developers!
We strongly suggest to do Test-Driven Development or Unit-Testing (test last). If you need inspiration, feel free to adapt directly the same tests we did.
Once you have written some tests, setup a Continuous Integration (CI) system to run the test suite and code linter automatically. We use travis-ci, but feel free to use the one that suits you best.
Also, we strive to keep our codebases with a unit test coverage of 80% or higher. We use coveralls to monitor test coverage.
These are the steps we followed to generate the Typescript DTOs (data transfer objects):
openapi-generator generate -i ./openapi3.yml -g typescript-node -o ./symbol-ts-sdk/ && rm -R symbol-ts-sdk/test
The SDK for TypeScript currently chooses the
typescript-node template from the OpenAPI Generator, but there are also other templates available to fit for other purposes. The SDK has interfaced out all the Http Repositories so that different implementations can be applied.
Example of repositories and implementations:
See the complete list of repositories and implementations.
By default, models are immutable and aim to hide the complexity, like type conversion or relationship between objects.
Example of models implementation:
See the complete list of models.
You will find in the implementations different invariants to ensure the object is well constructed and a nicer API is published.
Particular decisions we considered:
uint64, use that implementation instead.
uint64id. A specific endpoint returns the Namespace
The catbuffer library defines the protocol to serialize and deserialize Symbol entities.
In combination with the catbuffer-generators project, developers can generate builder classes for a given set of programming languages. For example, the Symbol SDK uses the generated code to operate with the entities in binary form.
If there is no generator for the programming language selected, you will need to develop it first. You can base your work on the generator for TypeScript.
If there is a generator, follow the next steps to generate the builders for all the existent entities:
git clone --recursive [email protected]:nemtech/catbuffer-generators.git
pip install -r requirements.txt
cpp_builderfor the targeted programming language.
python scripts/generate_all.sh cpp_builder
The previous command creates a new file for every schema under the
Here you can find some examples of how we used transactions builders:
See the complete list of transactions.
This section is incomplete.
Cryptographic functions are required to sign transactions. All the crypto-related functions can be found under the core/crypto module.
SDKs use standard
tweetnacl (ed2559) for key pair generation, address derivation (from public key) and signings:
Finally, pay special attention to the test vectors. The best way to make sure your implementation is correct is to use the test vectors files as inputs and expected outputs.
Examples of vector tests:
Services combine multiple REST API requests and provide developers with handy methods that cannot be retrieved directly from the API.
Services are considered “nice to have” features, and these usually are not required to consider the SDK complete. We recommend starting coding services only if you have a fully operational and well-tested SDK first.
Examples of services:
See the complete list of services.
The SDKs need to be adopted by other developers. As the main developer, no one knows better than you how the SDK works. Consider helping others and spread the usage of the SDK by providing the following documentation.
To make an SDK officially supported, submit it as a NIP. The reason behind the Symbol Improvement Proposal is to ensure that the new libraries are reviewed, tested, and shared among Symbol developers.
Did you find what you were looking for? Give us your feedback.