DAppNodeSDK

The DappnodeSDK dappnodesdk is a tool that makes creating and publishing new Dappnode packages as simple as possible. It helps to initialize, build, test, and publish the new package/repo to an APM tracked on the Ethereum Mainnet.

We have deployed a public APM (Aragon Package Manager) registry in which anyone can create their own APM repository: public.dappnode.eth

Install

$ npm install -g @dappnode/dappnodesdk

DEMO

Initialization

This command runs you through a setup wizard to begin creating the basic files for a new Dappnode Package Repo.

$ dappnodesdk init

Build

Only generates the IPFS Hash to be able to install it without needing to create the APM Repo

$ dappnodesdk build

Root and variant files

In a multi-variant package (--all_variants or --variants), each release is assembled from the package root and the variant directory (package_variants/<variant> by default):

• dappnode_package.json and docker-compose.yml are deep-merged, with the variant overriding the root.
• setup-wizard.* fields are merged by id, and notifications.yaml endpoints by correlationId. Within a matched entry, the variant's values override the root's, and an array from the variant (for example enum, conditions or alerts) replaces the root's array. The release contains exactly what was validated.
• Single files (avatar, prometheus-targets.*, disclaimer.md, getting-started.md, setup.schema.json, setup-target.json, setup-ui.json, signature.json) are taken from the variant directory when it has one, and otherwise from the root.
• Grafana dashboards (*grafana-dashboard.json) are collected from both the root and the variant.

Schema validation coerces some values (for example isBanner: "false" becomes false). The release ships the coerced value, and the build prints a warning in the "Validate files" step so the source file can be fixed.

Publish

It does the build of the image and shows the necessary transaction to be able to publish the package. The first time will create the repository but the rest will be updates of it.

To be able to update a repository you must be the authorized dev.

The script increases the current version of the repository based on the specified type (patch, minor, major), unless a version hasn't yet been published

For more information about versioning check semver

$ dappnodesdk publish < patch | minor | major >

Please take in account that the package version is not the internal version of the package you want to upload. We use Aragon package manager, and it only allows starting with version 1 and incrementing it one by one. Valid initial versions are 1.0.0, 0.1.0 or 0.0.1.

Troubleshooting

If your system does not find the binary dappnodesdk when running the command, please try the following alternative methods

• Run with npx which may handle better global NPM packages

npx @dappnode/dappnodesdk <command>

• Prefix the binary with the location of your global NPM package installation, for example:

~/.npm-packages/bin/dappnodesdk <command>

Github Actions

bump-upstream action

This Github Action automatically creates pull requests bumping the version to the latest released upstream version on DAppNode Packages. It then tests building the new bumped upstream version and automatically posts an IPFS hash if the build was successful so that the new version can be tested further with other Github Actions and by human testers.

Note: This action also requires a Pinata account with an API Access Token and a Github Personal Access Token stored in the repo's, individual's, or organization's secrets in order to work properly.

Sample Usage

.github/workflows/auto_check.yml

name: Bump upstream version

on:
  schedule:
    - cron: "00 */4 * * *"
  push:
    branches:
      - "master"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @dappnode/dappnodesdk github-action bump-upstream
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PINATA_API_KEY: ${{ secrets.PINATA_API_KEY }}
          PINATA_SECRET_API_KEY: ${{ secrets.PINATA_SECRET_API_KEY }}

You must specify in the package manifest what upstream Github repo the package is tracking. Also indicate what build variable in the docker-compose file should be updated.

dappnode_package.json

{
  "name": "prysm.dnp.dappnode.eth",
  "upstreamVersion": "v1.0.0",
  "upstreamRepo": "prysmaticlabs/prysm",
  "upstreamArg": "UPSTREAM_VERSION"
}

docker-compose.yml

version: "3.4"
services:
  beacon-chain:
    build:
      args:
        UPSTREAM_VERSION: v1.0.0

Internal dependencies

The dappnode SDK ueses the following internal dependencies to avoid code duplication across the dappnodeSDK, DNP_DAPPMANAGER and sdk-publish modules:

• @dappnode/types
• @dappnode/schemas

In order to have a better developing experience these modules lives inside the DNP_DAPPMANAGER repository

Development

Use Node.js 22.13+ or Node.js 24+ (Node.js 20 reached end of life in April 2026), and install the exact locked dependencies with yarn install --frozen-lockfile.

• yarn lint checks source and tests without changing files; yarn lint:fix applies automatic fixes.
• yarn build checks and compiles the SDK.
• yarn test runs deterministic regressions using temporary files, mocked Docker commands, and localhost HTTP servers. It does not need external credentials.
• yarn test:integration runs the live Docker/IPFS/Ethereum tests and requires those services to be available.

Terminal builds show numbered package/architecture stages and recent complete log lines; uploads display a separate waiting-for-pinning phase after transmission.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details