@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 versions 14 or higher.
Compatibility:
| Node Version | Stablility |
|---|---|
| v14.x.x | Stable |
| v16.x.x | Stable |
| v17.x.x | Stable |
| v18.x.x | Stable |
| v19.x.x | stable |
This service requires Node versions 18.14 or higher.
Compatibility:
| Node Version | Stablility |
|---|---|
| v18.14.x | Stable |
| v20.x.x | Stable |
| v21.x.x | Pending |
NOTE: Node LTS (long term support) versions start with an even number, and odd number versions are subject to a 6 month testing period with active support before they are unsupported. It is recommended to use sidecar with a stable actively maintained version of node.js.
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
To check your version you may append the --version flag to 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.
In the full endpoints doc, you will also find the following trace related endpoints :
/experimental/blocks/{blockId}/traces/operations?actions=false/experimental/blocks/head/traces/operations?actions=false/experimental/blocks/{blockId}/traces/experimental/blocks/head/tracesTo have access to these endpoints you need to :
—unsafe-rpc-externalBlocksTrace controller is active for the chain you are running.Currently BlocksTrace controller is active in Polkadot and Kusama.
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_KEEP_ALIVE_TIMEOUT: Set the keepAliveTimeout in express.SAS_SUBSTRATE_URL: URL to which the RPC proxy will attempt to connect to, defaults to
ws://127.0.0.1:9944. Accepts both a websocket, and http URL.Some chains require custom type definitions in order for Sidecar to know how to decode the data
retrieved from the node. 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). There is a helper CLI tool called generate-type-bundle that can generate a typesBundle.json file for you using chain information from @polkadot/apps-config. The generated json file from this tool will work directly with the SAS_SUBSTRATE_TYPES_BUNDLE ENV variable.
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:Whether 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: Whether or not to filter polkadot-js API-WS RPC logging, defaults to false.SAS_LOG_STRIP_ANSI: Whether or not to strip ANSI characters from logs, defaults
to false. Useful when logging RPC calls with JSON written to transports.SAS_LOG_WRITE: Whether or not to write logs to a log file. Default is set to false. Accepts a boolean value. The log files will be written as logs.log. NOTE: It will only log what is available depending on what SAS_LOG_LEVEL is set to.SAS_LOG_WRITE_PATH: Specifies the path to write the log files. Default will be where the package is installed.SAS_LOG_WRITE_MAX_FILE_SIZE: Specifies in bytes what the max file size for the written log files should be. Default is 5242880 (5MB). NOTE Once the the max amount of files have reached their max size, the logger will start to rewrite over the first log file.SAS_LOG_WRITE_MAX_FILES: Specifies how many files can be written. Default is 5.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.)
Prometheus metrics can be enabled by running sidecar with the following flag :
yarn start --prometheus
You can also define a custom port by running :
yarn start --prometheus --prometheus-port=<YOUR_CUSTOM_PORT>
The metrics endpoint can then be accessed :
http://127.0.0.1:9100/metrics orhttp://127.0.0.1:<YOUR_CUSTOM_PORT>/metricsThat way you will have access to the default prometheus metrics and one extra custom metric called sas_http_errors (of type counter). This counter is increased by 1 every time an http error has occured in sidecar.
It is possible to get more information about the fee and staking payout calculation process logged to the console. Because these calculations 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 --read-only -p 8080:8080 substrate-api-sidecar
# Or if you want to use environment variables set in `.env.docker`, run:
docker run --rm -it --read-only --env-file .env.docker -p 8080:8080 substrate-api-sidecar
NOTE: While you could omit the --read-only flag, it is strongly recommended for containers used in production.
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.
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. In order to update all the dependencies and resolutions run yarn up "@polkadot/*".
Ensure everything is up to date and working by running the following:
yarn
yarn dedupe
yarn build
yarn lint
yarn test
yarn test:historical-e2e-tests
yarn test:latest-e2e-tests
Commit the dependency updates with a name like fix(deps): update pjs api (title depending on what got updated, see commit history for other examples of this), and wait to get it merged.
Follow RELEASE.md next if you're working through a full sidecar release. This will involve creating a separate PR where the changelog and versions are bumped.
Sidecar is a stateless program and thus should not use any disk space.
The requirements follow the default of node.js processes which is an upper bound in HEAP memory of a little less than 2GB thus 4GB of memory should be sufficient.
Please note that if you run sidecar next to a substrate node in a single machine then your system specifications should improve significantly.
During the benchmarks we performed, we concluded that sidecar would use a max of 1.1GB of RSS memory.
The benchmarks were:
Hardware specs in which the benchmarks were performed:
Machine type:
n2-standard-4 (4 vCPUs, 16 GB memory)
CPU Platform:
Intel Cascade Lake
Hard-Disk:
500GB
19.0.0 (2024-04-24)
staking-payouts endpoint. More specifically:
erasStakersPaged and erasStakersOverviewerasStakersClipped is deprecated but still supported. It will be completely removed in the futurestaking-payouts endpoint. More specifically:
claimed false are now retrieved and returned in the endpoint's responseTested 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.