@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 12 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. You can define chain specific types in config/types.json. Read more about defining
types for polkadot-js here.
If you are connecting to Substrate Node Template, please add the following custom types in config/types.json.
{
"CUSTOM_TYPES": {
"Address": "AccountId",
"LookupSource": "AccountId"
}
}
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 yarn
Click here for full endpoint docs.
Sidecar should be compatible with any Substrate based chain, given constraints:
balances pallet.grandpa).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/block | 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.
The history of commits will be used to generate the CHANGELOG. To do so, run yarn deploy on the master
branch. This command will look at all the commits since the latest tag, bump the package version according
to semver rules, and generate a new CHANGELOG.
If you don't want to follow semver or need to do a dry run, consult the standard-version CLI usage
docs. Flags for standard-version can be passed to yarn deploy.
yarn deploy, which only does local operations and doesn't push anything, will output more or
less the following lines:
$ yarn deploy
yarn run v1.21.1
$ yarn build && standard-version -r minor
$ rimraf lib/ && tsc
✔ bumping version in package.json from 0.18.1 to 0.18.2
✔ outputting changes to CHANGELOG.md
✔ committing package.json and CHANGELOG.md
✔ tagging release v0.18.2
ℹ Run `git push --follow-tags origin master && npm publish` to publish
To publish the new package, just follow the instructions: git push --follow-tags origin master && npm publish.
You must have access to the @substrate organization on npm to publish.
11.1.1 (2021-11-04)
Upgrade priority: Low
-fix: optimize pallets-storage (#739) (30d446)
Tested against:
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.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.