search

vechain / vechain-sdk-js

The official JavaScript SDK for VeChain.
19 stars 6 forks source link

readme

vechain-sdk-js

The official JavaScript SDK for vechain.

main-ci Quality Gate Status Coverage Security Rating Maintainability Rating License: MIT

Introduction

🚀 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! 🌌🔮

Repository Structure

Welcome to the VeChain SDK repository! Here's a breakdown of our organized structure:

Explore, experiment, and let the VeChain SDK empowers your blockchain adventures!

SDK Development

Prerequisites

Note
Docker is required for setting up a local thor-solo node for integration testing.

Additional prerequisites for Windows 10

Docker Desktop needs the run on Windows 10 patched at the level 21H2 (19044 build). The last level provided by Windows 10 automatic upgrade is 21H1 (1043 build). To install Docker Desktop to run Thor Solo to develop with this SDK, and Windows 10 is not patched with a build higher than 19043, follows the instructions published in the KB5015684 Featured Update Windows 10 to 22H2 guide.

  1. Update Windows 10 to the last available level, if this is not 21H2 (19044 build) go to step 2.
  2. From Start - Settings - Update & Security - Windows Update panel, see if the link View Optional Updates is visible and clickable, else go to step 3.
  3. From Start - Settings - Update & Security opt in the Windows Insider Program.
  4. From Start - Settings - Update & Security - Windows Update panel, click View Optional Updates and install all the available patches.

Additional prerequisite for Windows OS

This SDK is supposed to be downloaded and installed with Git. Yarn scripts are distributed according Linux/MacOS/Unix shell specifications. To let Windows OS to manage Git distributed software, to install and upgrade this SDK and run Yarn scripts, please, follow the instructions below.

  1. Install the official Git for Windows. The installation deploys the Git Bash - MINGW terminal in Windows 0S, providing a terminal compatible with the Yarn scripts used in this SDK.
  2. From Startmenu, click Git Bash to open the terminal compatible with the Yarn scripts. You are now
  3. ready to getting started.

Configure JetBrains IDE to use Git Bash

Getting Started

  1. Clone your forked repository.
  2. Navigate to the project directory.
  3. Run yarn install to install all dependencies.

Commands

Integration Testing

This section provides guidance on conducting integration tests using a local thor-solo node. Ensure Docker is operational on your system before proceeding.

Setting Up

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.

Running Tests

There are two ways to run tests:

  1. 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.

  2. 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.

Running tests in a browser-like environment

The SDK fully support execution in a browser environment. To run the tests in a browser-like environment, you can use the yarn test:browser command. This command requires a local thor-solo node to be running. Alternatively, you can run the tests with thor-solo by using the yarn test:browser:solo command. This command will start thor-solo, run the tests, and stop thor-solo at the end.


### Custom thor-solo Data Starting Point

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.

#### Creating a Custom LevelDB Snapshot

1. **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.

2. **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

3. **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.

#### Using the Custom Snapshot

1. **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.

2. **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.

3. **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.

## Documentation and Examples

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.

### Examples

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:
``` bash
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.

Templates

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]

Code Snippets

It's also possible to include just a code snippet from an example file. For instance:

DeployContractSnippet

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.

Usage

To build the documentation, expanding examples into code snippets, use:

yarn build

Architecture diagrams

For a comprehensive overview of the package structure, please refer to our Architecture Diagrams located in the documentation directory.

Experimental Features

We are continuously working on new features and improvements to enhance the SDK. You can enable experimental features of specific cryptographic modules by use useExperimentalCryptography function of a specific module.

For example:

keystore.useExperimentalCryptography(true)

Troubleshooting

Next.js

Projects based on Next.js need the root tsconfig.json file includes the options

{
  "compilerOptions": {
    "target": "es2020",
    "types": [
      "@testing-library/jest-dom"
    ]
  }
}

to define the runtime and the test framework to be compatible with the ECMAScript 2020 language specifications.

An example of Next.js tsconfig.json is available in the module sdk-nextjs-integration.

Next.js caches data types when dependencies are installed and the project is built. To be sure the options defined in tsconfig.json are effective when changed, delete the directories .next, node_modules and the file next-env.d.ts from the root directory of the project, then rebuild the project.

Contributing

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.

License

This project is licensed under the MIT license.

Publishing

The VeChain SDK uses Changesets CLI. To publish a new release:

yarn pre-release X.Y.Z
yarn changeset publish
yarn post-release X.Y.Z

Finally, update also the documentation.

Contact information