@substrate/api-sidecar
Advanced tools
REST service that makes it easy to interact with blockchain nodes built using Substrate's FRAME framework.
v1.0.0 was released on 2020-10-23. This major release introduced several renamed endpoints as breaking changes. It is important that users complete the transition to the new endpoints ASAP so they are ready for any subsequent emergency updates. Please visit the MIGRATION_GUIDE to learn more.
This service requires Node version 14 or higher.
Install the service globally:
npm install -g @substrate/api-sidecar
# OR
yarn global add @substrate/api-sidecar
Run the service from any directory on your machine:
substrate-api-sidecar
Install the service locally:
npm install @substrate/api-sidecar
# OR
yarn add @substrate/api-sidecar
Run the service from within the local directory:
node_modules/.bin/substrate-api-sidecar
Jump to the configuration section for more details on connecting to a node.
Click here for full endpoint docs.
Simply run yarn.
If you are looking to hack on the calc Rust crate make sure your machine has an up-to-date version of rustup
installed to manage Rust dependencies.
Install wasm-pack if your machine does not already have it:
cargo install wasm-pack
Use yarn to do the remaining setup:
yarn
# For live reload in development
yarn dev
# To build and run
yarn build
yarn start
Jump to the configuration section for more details on connecting to a node.
To use a specific env profile (here for instance a profile called 'env.sample'):
NODE_ENV=sample yarn start
For more information on our configuration manager visit its readme here. See Specs.ts to view the env configuration spec.
SAS_EXPRESS_BIND_HOST: address on which the server will be listening, defaults to 127.0.0.1.SAS_EXPRESS_PORT: port on which the server will be listening, defaults to 8080.SAS_EXPRESS_LOG_MODE: enable console logging of "all" HTTP requests, only "errors", or nothing by
setting it to anything else. LOG_MODE defaults to only "errors".SAS_SUBSTRATE_WS_URL: WebSocket URL to which the RPC proxy will attempt to connect to, defaults to
ws://127.0.0.1:9944.Some chains require custom type definitions in order for Sidecar to know how to decode the data retrieved from the node. Sidecar pulls types for chains from @polkadot/apps-config, but in some cases the types for the chain you are trying to connect to may be out of date or may simply not exist in @polkadot/apps-config.
Sidecar affords environment variables which allow the user to specify an absolute path to a JSON file
that contains type definitions in the corresponding formats. Consult polkadot-js/api for more info on
the type formats (see RegisteredTypes).
N.B Types set from environment variables will override the corresponding types pulled from @polkadot/apps-config.
SAS_SUBSTRATE_TYPES_BUNDLE: a bundle of types with versioning info, type aliases, derives, and
rpc definitions. Format: OverrideBundleType (see typesBundle).SAS_SUBSTRATE_TYPES_CHAIN: type definitions keyed by chainName. Format: Record<string, RegistryTypes> (see typesChain).SAS_SUBSTRATE_TYPES_SPEC: type definitions keyed by specName. Format: Record<string, RegistryTypes> (see typesSpec).SAS_SUBSTRATE_TYPES: type definitions and overrides, not keyed. Format: RegistryTypes (see types).You can read more about defining types for polkadot-js here.
Polkadot-js can recognize the standard node template and inject the correct types, but if you have
modified the name of your chain in the node template you will need to add the types manually in a
JSON types file like so:
// my-chains-types.json
{
"Address": "AccountId",
"LookupSource": "AccountId"
}
and then set the enviroment variable to point to your definitions:
export SAS_SUBSTRATE_TYPES=/path/to/my-chains-types.json
SAS_LOG_LEVEL: the lowest priority log level to surface, defaults to info. Tip: set to http
to see all HTTP requests.SAS_LOG_JSON: wether or not to have logs formatted as JSON, defaults to false.
Useful when using stdout to programmatically process Sidecar log data.SAS_LOG_FILTER_RPC: wether or not to filter polkadot-js API-WS RPC logging, defaults to false.SAS_LOG_STRIP_ANSI: wether or not to strip ANSI characters from logs, defaults
to false. Useful when logging RPC calls with JSON written to transports.Log levels in order of decreasing importance are: error, warn, info, http, verbose, debug, silly.
| http status code range | log level |
|---|---|
code < 400 | http |
400 <= code < 500 | warn |
500 < code | error |
If looking to track raw RPC requests/responses, one can use yarn start:log-rpc to turn on polkadot-js's
logging. It is recommended to also set SAS_LOG_STRIP_ANSI=true to increase the readability of the logging stream.
N.B. If running yarn start:log-rpc, the NODE_ENV will be set to test. In order still run your .env
file you can symlink it with .env.test. For example you could run
ln -s .env.myEnv .env.test && yarn start:log-rpc to use .env.myEnv to set ENV variables. (see linux
commands ln and unlink for more info.)
It is possible to get more information about the fee and payout calculation process logged to the console. Because this fee calculation happens in the statically compiled web assembly part a re-compile with the proper environment variable set is necessary:
CALC_DEBUG=1 sh calc/build.sh
Click here for full endpoint docs.
Click here for chain integration guide.
With each release, the maintainers publish a docker image to dockerhub at parity/substrate-api-sidecar
docker pull docker.io/parity/substrate-api-sidecar:latest
The specific image tag matches the release version.
yarn build:docker
# For default use run:
docker run --rm -it -p 8080:8080 substrate-api-sidecar
# Or if you want to use environment variables set in `.env.docker`, run:
docker run --rm -it --env-file .env.docker -p 8080:8080 substrate-api-sidecar
then you can test with:
curl -s http://0.0.0.0:8080/blocks/head | jq
N.B. The docker flow presented here is just a sample to help get started. Modifications may be necessary for secure usage.
Need help or want to contribute ideas or code? Head over to our CONTRIBUTING doc for more information.
All the commits in this repo follow the Conventional Commits spec. When merging a PR, make sure 1) to use squash merge and 2) that the title of the PR follows the Conventional Commits spec.
Checkout a branch name-v5-0-1. When deciding what version will be released it is important to look over 1) PRs since the last release and 2) release notes for any updated polkadot-js dependencies as they may affect type definitions.
Ensure we have the latest polkadot-js dependencies. Note: Every monday the polkadot-js ecosystem will usually come out with a new release. It's important that we keep up, and read the release notes for any breaking changes, or high priority updates. You can use the following command yarn upgrade-interactive to find and update all available releases. Feel free to update other packages that are available for upgrade if reasonable. To upgrade just @polkadot scoped deps use yarn up "@polkadot/*"
After updating the dependencies, the next step is making sure the release will work against all relevant runtimes for Polkadot, Kusama, and Westend. This can be handled by running yarn test:init-e2e-tests. You must have python3, and the dependencies inside of ./scripts/requirements.txt installed to run the script (Read the README for more instructions). Before moving forward ensure all tests pass, and if it warns of any missing types feel free to make an issue here. Note that the e2e tests will connect to a running node in order to test sidecar against real data.
You can also run the e2e tests for each chain individually with: yarn test:e2e-tests --chain polkadot (start sidecar in a separate terminal, with SAS_SUBSTRATE_WS_URL set to the appropriate rpc node, e.g.: wss://rpc.polkadot.io, wss://kusama-rpc.polkadot.io, wss://westend-rpc.polkadot.io)
Update the version in the package.json (this is very important for releasing on NPM).
Update CHANGELOG.md by looking at merged PRs since the last release. Follow the format of previous releases. Only record dep updates if they reflect type definition updates as those affect the users API.
Make sure to note if it is a high upgrade priority (e.g. it has type definitions for an upcoming runtime upgrade to a Parity maintained network).
Commit with ex: chore(release): 5.0.1, then git push your release branch up, make a PR, get review approval, then merge.
NOTE: Before pushing up as a sanity check run the following 4 commands and ensure they all run with zero errors. There is one exception with yarn test where you will see errors logged, that is expected as long as all the test suites pass.
yarn dedupe
yarn build
yarn lint
yarn test
Now that master has the commit for the release, pull down master branch.
Make sure the tag reflects your corresponding version, and run:
git tag v5.0.1
git push origin v5.0.1
Go to tags on github, inside of the repo, and click the three dots to the far right and select the option to create a release.
Generally you can copy the changelog information and set the release notes to that. You can also observe past releases as a reference.
NOTE: You must be a member of the @substrate NPM org and must belong to the Developers team within the org. (Please make sure you have 2FA enabled.)
Now that master has the commit for the release, pull down master branch.
Run the following commands. (Please ensure you have 2FA enabled)
npm login # Only necessary if not already logged in
yarn deploy # Builds JS target and then runs npm publish
FAQs
REST service that makes it easy to interact with blockchain nodes built using Substrate's FRAME framework.
The npm package @substrate/api-sidecar receives a total of 257 weekly downloads. As such, @substrate/api-sidecar popularity was classified as not popular.
We found that @substrate/api-sidecar demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."