SDK の最初のグループを構築するときに私たちが持っていた主な目的の 1 つは、開発者がまったく異なる設計に適応することなく、プログラミング言語間で迅速に変更できるようにすることでした。このドキュメントは相互運用性を実現するために、同じ設計を共有する Symbol ベースの SDK を出荷するように開発者をガイドすることを目的としています。
インフラストラクチャ
このパッケージには生成された API クライアントと DTO が含まれています。HTTP リクエストはリポジトリパターンに則しており、これらはオブザーバルパターンを介して Symbol の変更不可なモデルを返します。
モデル
Symbol ドメインモデルは定義によっては不変ですが、開発者はその属性を変更できません。代わりに、開発者は新しいトランザクションを作成して TransactionHTTP 経由でブロックチェーンへ送信する必要があります。
サービス
複数の REST API リクエストを結合する必要がある一般的な操作
標準化された契約: データモデルの相互運用性と調和を保証する。
疎結合: コンポーネントの結合度合いを取り除く。
抽象化: 相互運用性の長期的な一貫性を高め、基礎となるコンポーネントを独立して進化させる。
再利用性: モジュールとコンポーネント利用者間での高いレベルの相互運用性。
ステートレス: コンポーネントの可用性と拡張性を高め、より頻繁で信頼できる相互運用を可能にします。
合成性: 効果的なコンポーネントの構成のために、相互運用可能でなければなりません。
Symbol SDK は ReactiveX Library ライブラリを多用しています。
リアクティブアプローチを使用する利点は次のとおりです:
機能性: 開発者はオブザーバブルなストリームにクリーンな入出力関数を使用して、複雑でステートフルなプログラムを避けることができます。
少ない事で多くの事を: 大抵の場合、ReactiveX オペレータは複雑なコードを数行のコードへ還元します。
非同期的エラーハンドリング: 伝統的な try/catch は非同期処理でのエラー処理には非力ですが、ReactiveX はエラーを処理するための適切なツールを開発者に提供します。
並列処理: ReactiveX のオブザーバブルとスケジューラは、プログラマへの低水準のスレッディング、同期、並行処理の実装を抽象化することができます。
フロントエンド: Web上で RxJS を使用したUIイベントとAPI応答の操作。
バックエンド: ReactiveX の非同期性を利用し、同時性と実装の独立性を可能にします。
リアクティブプログラミングを初めて使用する場合は、オンラインガイド Learn RxJS から始めることをお勧めします。
Symbol ビルドイン機能 に詳しくなるためにはテクニカルドキュメントを見てください。
Symbol の ローカル環境を Docker で セットアップします。
API リファレンス を確認して、エンドポイントを実行してみてください。
Symbol に関する質問をするために Discord に参加してください。
作成しようとしている SDK にまだ誰も取り組んでいないことを確認してください。リポジトリリスト をチェックし #sig-api チャンネルであなたの意向をコメントしてください。
このリポジトリをフォークしている そのSDK を要求して リポジトリリスト に新しいエントリを追加してください。
TypeScript SDK に基づいた開発を行うことができます。SDK は TypeScript の最新バージョンに追従します。コードの更新については Changelog を確認してください。
可能であれば GitHub で新しいリポジトリを作成します:
SDK のインストール手順の README
貢献ガイドライン はどのように他の人を手助けできるかについて記述しています。
良好なテストカバレッジのプロジェクトは開発者にとって、より信頼のおけるものとなるでしょう。
テスト駆動開発 またはユニットテスト (継続テスト) を 強く 推奨します。インスピレーションが必要な場合は、私たちが行っているテストと同じように、直接適応させてください。
travis.yml 設定ファイル の例
ユニットテスト の例
エンドツーエンドテスト の例
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.
また、私たちはコードのユニットテストカバレッジを 80% 以上にするように努力しています。 coveralls を使用してカバレッジを確認しています。
The OpenAPI Generator handles the API and DTOs generation. It supports multiple languages, and hopefully, yours is on the list.
Typescript DTO (データ転送オブジェクト) を生成するために実行した手順は次のとおりです:
最新の Symbol OpenAPI 仕様 を Github リリースからダウンロード
OpenAPI ジェネレータ CLI のインストール
npm install @openapitools/openapi-generator-cli@cli-4.1.0 -g
選択したプログラミング言語向けの DTO を生成する。
openapi-generator generate -i ./openapi3.yml -g typescript-node -o ./symbol-ts-sdk/ && rm -R symbol-ts-sdk/test
The generated lib is normally published into a central repository (e.g. maven, npm). The SDKs depend on those libraries like any other third party dependency. To automate the deployment of the packages, including the generator for the selected programming language in the symbol-openapi-generator project.
Drop the generated client classes and implement them using the Repository pattern returning Observables of ReactiveX.
注釈
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.
リポジトリ実装の例:
リポジトリと実装 のリストを参照
The repositories return models instead of DTOs. You will need to code the models before finishing the API wrapper.
デフォルトでは、型変換やオブジェクト間の関係などの複雑さを隠蔽することを目的として、モデルは不変となっています。
モデル実装の例:
モデル のリストを参照
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 support: While Java supports big numbers, for example, JavaScript doesn't. The JavaScript SDK has a custom class to handle the uint64 types. If your language supports uint64, use that implementation instead.
API 変換: API によって返されるデータは圧縮される場合があります。ユーザーのこれらのタイプを変換する必要がある場合があります。
ネームスペース ID: 作成時には文字列名を追加しますが、ネットワークからネームスペースを取得すると uint64 IDとしてフォーマットされます。特定のエンドポイントは 文字列 のネームスペース名を返します。
The catbuffer-schemas 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:
catbuffer-generators リポジトリをクローンしてください。
git clone --recursive git@github.com:symbol/catbuffer-generators.git
必須パッケージをインストール
pip install -r requirements.txt
catbuffer-schemas リポジトリを catbuffer-generators の中にクローンしてください。
Generate code for all the schemas running the following command under the catbuffer-generators directory, replacing cpp_builder for the targeted programming language.
python scripts/generate_all.sh cpp_builder
直前のコマンドは catbuffer/_generated/cpp_builder フォルダの下に各スキーマの新しいファイルを作成します。
Publish the generated code into a central repository (e.g. Maven, NPM) and make the SDK dependant on this library. For every transaction type, use the generated builders to serialize and deserialize transactions.
Here you can find some examples of how we used transactions builders:
トランザクション のリストを参照
注釈
このセクションは未完了です。
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:
Keypairs are based on tweetnacl 64 bytes secretKey (public + private) using SHA-512.
Signatures use tweetnacl detached mode and also get generated using SHA-512.
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.
ベクタテストの例:
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.
サービスの例:
AggregateTransactionService: Helps application developers to announce aggregate transactions without having to develop the logic to wait for the hash lock confirmation.
MetadataTransactionService: Creates metadata transactions without having to pass the previous value.
BlockService: Provides with methods to verify that the data returned by a given node is valid.
サービス のリストを参照
SDK は他の開発者に採用される必要があります。メイン開発者であるならば、 SDK がどのように機能するかをあなたより知っている人は誰もいません。 次のドキュメント を提供して、他の人を助け、SDK の使用を広めることを検討してください。
Apache-2.0: Apache License, version 2.0
BSD-2-Clause: OSI-approved BSD 2-clause license
BSD-3-Clause: OSI-approved BSD 3-clause license
CC0-1.0: Creative Commons CC0 1.0 Universal
GNU-All-Permissive: GNU All-Permissive License
LGPL-2.1+: GNU Lesser General Public License (LGPL), version 2.1 or newer
