Dependencies

Properly declaring dependencies is crucial for ensuring your Blocklet is stable, portable, and runs correctly in any environment. In blocklet.yml, dependencies are defined in two main categories: system-level requirements and dependencies on other Blocklets, known as components.

This guide covers how to configure both the requirements and components sections of your metadata file. For details on the runtime environment itself, see the Execution guide.

System Requirements#

The requirements object specifies the minimum environment constraints your Blocklet needs to function. This includes the required versions of Blocklet Server, Node.js, and compatible operating systems or CPU architectures.

Property	Type	Description	Default
server	string (semver)	The compatible version range for Blocklet Server.	"^1.16.8"
os	string or string[]	The compatible operating system(s). Valid values include darwin, linux, etc.	"*" (any)
cpu	string or string[]	The compatible CPU architecture(s). Valid values include x64, arm64, etc.	"*" (any)
nodejs	string (semver)	The compatible Node.js version range.	"*" (any)
abtnode	string (semver)	The compatible version range for the underlying ABT Node.	N/A

Example: Specifying System Requirements#

Here is an example of a requirements configuration for a Blocklet that needs a specific version of Blocklet Server and Node.js, and is optimized for Linux on x64 or arm64 architectures.

Pre-funded Accounts (Fuels)#

For Blocklets that interact with a blockchain, you can request that one or more accounts be pre-funded with tokens upon installation. This is handled by the fuels array within requirements. This feature is essential for Blocklets that need to pay transaction fees for setup tasks, such as deploying a smart contract.

Each object in the fuels array defines a funding request.

Property	Type	Description
endpoint	string	Required. The endpoint of the blockchain network to interact with.
value	string	Required. The amount of tokens requested.
reason	string	Required. A human-readable explanation for why the funding is necessary.
address	string	The specific address to fund. If omitted, the system uses a default address.

Example: Requesting Fuel#

This example requests 0.1 ETH to cover the gas fees for deploying a contract during the Blocklet's installation process.

Blocklet Components#

The components field allows your Blocklet to depend on other Blocklets. This creates a powerful composition model, where you can build complex applications by assembling smaller, independent, and reusable Blocklets. When a user installs your Blocklet, its components are installed alongside it.

Each item in the components array defines a single dependency.

Property	Type	Description
source	object	Required. Defines where to fetch the component Blocklet. See sourcing methods below.
required	boolean	If true, this component is mandatory. The parent Blocklet cannot start without it. Defaults to false.
title	string	A suggested title for the component instance when it's installed.
description	string	A suggested description for the component instance.
mountPoint	string	A suggested URL path where the component's interface will be mounted.

Sourcing Components#

You can source a component from a public Blocklet Store or directly from a URL.

1. From a Blocklet Store (Recommended) This is the standard approach for public and version-managed components. The source object requires store, name, and version.components:
- source:
store: "https://store.arcblock.io/api/blocklets"
name: "did-connect"
version: ">=2.0.0"
required: true
title: "User Authentication"
mountPoint: "/login"


2. From a URL This method is useful for development, private components, or components not listed in a store. The source object requires a url pointing to the component's blocklet.json file.components:
- source:
url: "https://github.com/arcblock/blocklet-example/releases/download/v0.1.0/blocklet.json"
required: false
title: "My Custom Component"



By clearly defining your Blocklet's dependencies, you ensure a smooth and predictable experience for users. Now that you've configured the dependencies, you can explore enabling optional features.

Next, learn how to configure built-in capabilities in the Features section.