🚀 Welcome to the vechain SDK, your passport to the dazzling universe of decentralized wonders on the vechain blockchain. Brace yourself for a coding adventure like no other! Whether you're a blockchain bard or a coding wizard, our SDK is your key to unlocking the mysteries of secure and seamless blockchain development. Join us in this epic journey, where lines of code transform into spells of innovation, and every commit propels you deeper into the enchanted realms of VechainThor. Ready to embark on a coding odyssey? Let the vechain SDK be your guide! 🌌🔮
Welcome to the vechain SDK repository! Here's a breakdown of our organized structure:
./docs
: Your go-to destination for comprehensive documentation. Explore demonstrative examples showcasing the prowess of our SDK. Knowledge is power, and our docs are here to enlighten your path../packages
: A hub for our monorepo packages, each serving a distinct purpose:./packages/core
: The heart of the SDK, housing essential modules for fundamental operations like hashing and cryptography. Dive into the core for the building blocks of your decentralized dreams../packages/errors
: Delve into the world of error handling with the error package. This module is dedicated to managing and customizing errors within the SDK, ensuring your development experience remains resilient and smooth../packages/hardhat-plugin
: Seamlessly integrate the vechain SDK with Hardhat, the Ethereum development environment. This plugin provides a bridge between the vechain SDK and the Ethereum ecosystem, enabling you to leverage the best of both worlds../packages/logging
: The logging package provides a simple and easy-to-use logging system for the vechain SDK. This module is dedicated to managing and customizing logs within the SDK, ensuring your development experience remains transparent and insightful../packages/network
: Embark on a journey through the network module, your gateway to all things related to blockchain interaction and transaction dissemination. Here, the vechain SDK connects you seamlessly to the VechainThor blockchain../packages/provider
: Get the maximum of EVM development stack with provider package. This module is dedicated to managing the compatibility with ethers and EVM world../packages/wallet
: Secure your assets and manage transactions with ease using the wallet package. This module provides functionality for creating and managing vechain wallets, as well as signing and broadcasting transactions securely on the VechainThor blockchain../packages/rpc-proxy
: This package is designed to bridge the gap between Thor's RESTful API and Ethereum's JSON-RPC.
Explore, experiment, and let the vechain SDK empowers your blockchain adventures!
Note
Docker is required for setting up a local thor-solo node for integration testing.
- Clone your forked repository.
- Navigate to the project directory.
- Run
yarn install
to install all dependencies.
- Build: Execute
yarn build
to build the project. - Test: Execute
yarn test:solo
to run all tests.- NOTE: Integration tests require a local thor-solo node. See the Integration Testing section for more details.
- Lint: Execute
yarn lint
to lint all packages. - Format: Execute
yarn format
to format all packages.
This section provides guidance on conducting integration tests using a local thor-solo node. Ensure Docker is operational on your system before proceeding.
The integration tests interact with a local thor-solo node.
This node uses the thor-solo/instance-a4988aba7aea69f6-v3/main.db
data directory,
which is pre-configured with a block history and 20 seeded accounts for testing.
There are two ways to run tests:
-
Manual start of thor-Solo node:
- To start the thor-Solo node manually, use the command
yarn start-thor-solo
. - Once the local thor-Solo node is running, integration tests can be executed with
yarn test
. - After testing is complete, stop the node with
yarn stop-thor-solo
.
- To start the thor-Solo node manually, use the command
-
Simple execution:
- For a more straightforward approach, use
yarn test:solo
. - This command handles the thor-Solo node's start and stop processes for you.
- For a more straightforward approach, use
For advanced testing scenarios, you may require a custom data starting point with thor-solo. This involves creating a custom snapshot of thor's LevelDB.
-
Start thor-solo with Persistence:
- Launch thor-solo using Docker with the
--persist
flag. This enables data persistence. - Use the
--data-dir
flag to specify the directory where thor-solo will store its data.
- Launch thor-solo using Docker with the
-
Perform Transactions:
- Execute the necessary transactions or operations in thor-solo. These transactions will be recorded in the specified data directory.
- An example of transactions performed to seed the 20 accounts is found in the
thor-solo-seeding.ts
file
-
Export LevelDB:
- Once you've completed the transactions, use a tool like
docker cp
to export the LevelDB directory (i.e.,instance-a4988aba7aea69f6-v3
) from the Docker container.
- Once you've completed the transactions, use a tool like
-
Prepare the Dockerfile:
- Modify the Dockerfile used for building the thor-solo container. Ensure it copies the exported LevelDB snapshot into the correct path within the container.
-
Update Data Directory Path:
- Adjust the
--data-dir
flag in your thor-solo startup script or Docker command to point to the new LevelDB snapshot location within the container.
- Adjust the
-
Restart thor-solo:
- Rebuild and restart the thor-solo container with the updated Dockerfile. This will launch thor-solo with your custom data starting point.
On the /docs
folder you can find the comprehensive SDK documentation and executable code examples.
We've designed these examples not just for learning purposes but also as integration tests,
ensuring that the provided code snippets are always functional and up to date.
Our code examples reside in the ./docs/examples
folder. Each example is a stand-alone script that showcases various operations achievable with the SDK. Some of the code examples require a Thor Solo node to be available.
To run the scripts within ./docs/examples
as tests, use:
yarn test:examples
NOTE: Tests require thor-solo to be running locally. You can run and stop separately thor solo node with yarn start-thor-solo
and yarn stop-thor-solo
or run all tests with yarn test:examples:solo
which will start thor solo node, run all tests and stop thor solo at the end.
In the ./docs/templates
folder, you'll find markdown files used to build our final documentation. These templates can include links to example files, dynamically expanded into code snippets during documentation generation.
For instance:
[example](examples/accounts/bip39.ts)
The above link, when processed during documentation build, expands into the content of the linked file, ensuring our documentation is as practical as possible.
Note: links that are to be expanded must have a text [example]
It's also possible to include just a code snippet from an example file. For instance:
[DeployContractSnippet](examples/contracts/contract-create-ERC20-token.ts)
Will just include into the documentation the code snippet between the comments // START_SNIPPET: DeployContractSnippet
and // END_SNIPPET: DeployContractSnippet
in the file examples/contracts/contract-create-ERC20-token.ts
.
Important: The code snippets names must be unique across all examples and must end with the word "Snippet".
In this way we can keep the examples dry and avoid duplicating code.
To build the documentation, expanding examples into code snippets, use:
yarn build
For a comprehensive overview of the package structure, please refer to our Architecture Diagrams located in the documentation directory.
- You can also create and test your examples using
yarn test:examples
command (with soloyarn test:examples:solo
).
If you want to contribute to this project and make it better, your help is very welcome. Contributing is also a great way to learn more about social coding on GitHub, new technologies and their ecosystems and how to make constructive, helpful bug reports, feature requests and the noblest of all contributions: a good, clean pull request.
For more details and guidelines on how to contribute, refer to CONTRIBUTING.
This project is licensed under the MIT license.
The vechain SDK uses Changesets CLI
. To publish a new release:
yarn prepare-packages X.Y.Z
yarn changeset publish
-
Support https://support.vechain.org
@@@@@@@@@@@@@@ /@@@@@ @@@@@@@@@@@@@@@@ @@@@@@ @@@@@@ @@@@@ @@@@@ @@@@@ @@@@@ @@@@@ @@@@@ @@@@@& @@@@@ @@@@@ @@@@@@ %@@@@@ @@@@@ @@@@@ @@@@@% @@@@@@ @@@@@ @@@@@ @@@@@ @@@ @@@@@ @@@@@ @ @@@@@ @@@@@ @@@@@@ @@@@@ @@@@@# @@@@@@ @@@@@ @@@@@@@@@ @@@@@@@