Skip to main content

​
Overview

The init command guides you through setting up a new node extension in your project. It populates the node_extensions section in your tenderly.yaml file by linking a custom RPC method to an existing Web3 Action. 
tenderly node-extensions init [flags]

​
Prerequisites

Before initializing an extension, ensure you have:
  1. Authenticated with Tenderly 
    tenderly login
  2. At least one eligible Web3 Action configured in tenderly.yaml with:
    • Trigger type: webhook
    • Webhook authentication: false
    • Not already used by another extension
The init command will fail if you don’t have any eligible actions. Make sure to create a Web3 Action with a non-authenticated webhook trigger first.

​
Flags

​
--name
string
required
Name for the extension. This is a unique identifier used in your tenderly.yaml configuration.
--name my-custom-balance
​
--description
string
Human-readable description of what the extension does. Helps document the purpose of your custom RPC method.
--description "Calculate custom token balance with vesting"
​
--methodName
string
required
The JSON-RPC method name that will be used to call this extension. Must follow the naming convention.Requirements:
  • Must start with extension_
  • Followed by a lowercase letter
  • At least 3 characters after the prefix
  • Can contain letters and numbers
  • Use camelCase (no underscores after the prefix)
  • Must match regex: ^extension_[a-z][A-Za-z0-9]{2,}(?:[A-Z][a-z0-9]+)*$
--methodName extension_getCustomBalance

​
Interactive Mode

When you run the init command, if multiple eligible actions are available, you’ll be prompted to select which action to use with your extension: 
$ tenderly node-extensions init --name my-extension --methodName extension_myMethod

? Select action to use with extension:
  ▸ my-account/my-project:custom-webhook-action
    my-account/my-project:another-webhook-action
Use arrow keys to select the action, then press Enter.

​
Examples

​
Basic Initialization

Initialize an extension with required flags: 
tenderly node-extensions init \
  --name token-balance \
  --description "Get token balance with custom logic" \
  --methodName extension_getTokenBalance

​
Custom Data Aggregation

Create an extension for aggregating data from multiple sources: 
tenderly node-extensions init \
  --name aggregate-portfolio \
  --description "Aggregate portfolio data across multiple protocols" \
  --methodName extension_getPortfolioValue

​
Transaction Validation

Set up an extension for custom transaction validation: 
tenderly node-extensions init \
  --name validate-tx \
  --description "Validate transactions against custom rules" \
  --methodName extension_validateTransaction

​
Configuration Result

After successful initialization, the command updates your tenderly.yaml file:
tenderly.yaml
node_extensions:
  my-account/my-project:
    specs:
      token-balance:  # From --name flag
        description: Get token balance with custom logic
        method: extension_getTokenBalance  # From --methodName flag
        action: custom-webhook-action      # Selected from prompt

​
Validation and Errors

The init command performs several validations:

​
Invalid Method Name

If your method name doesn’t match the required pattern: 
$ tenderly node-extensions init --name test --methodName my_method

Error initializing extensions: invalid method name: my_method
Please make sure that your extension's method name satisfies the following regex:
^extension_[a-z][A-Za-z0-9]{2,}(?:[A-Z][a-z0-9]+)*$
Common mistakes:
  • Not starting with extension_
  • Using underscores after the prefix
  • Starting with uppercase or number after prefix
  • Method name too short (less than 3 chars after prefix)

​
No Eligible Actions

If no actions with non-authenticated webhook triggers exist: 
Error initializing extensions: no actions found in tenderly.yaml that can be
used to create a extension.
Please make sure that you have at least one action in tenderly.yaml which has
a non authenticated webhook trigger.
Solution: Add a Web3 Action with a webhook trigger:
tenderly.yaml
actions:
  my-account/my-project:
    - name: my-webhook-action
      function: actions/myAction.ts
      trigger:
        type: webhook
        webhook:
          authenticated: false  # Required for extensions

​
All Actions Already In Use

If all eligible actions are already associated with extensions: 
Error initializing extensions: all eligible actions are already used by
extensions in tenderly.yaml
Please make sure that you have at least one action in tenderly.yaml which has
a non authenticated webhook trigger and isn't used by any extension.
Solution: Create a new action or remove an existing extension.

​
Duplicate Method Name

If the method name is already used by another extension in the same project: 
Error initializing extensions: method name extension_myMethod is already used
by another extension in project `my-account/my-project`.
Please choose a different method name for your new extension.
Solution: Use a unique method name.

​
Workflow

1

Create Web3 Action

First, ensure you have a Web3 Action with a non-authenticated webhook trigger in your tenderly.yaml.
2

Run Init Command

Execute the init command with your desired extension name and method name:
tenderly node-extensions init \
  --name my-extension \
  --description "Description of my extension" \
  --methodName extension_myMethod
3

Select Action

If prompted, select which action to use from the list of eligible actions.
4

Verify Configuration

Check your tenderly.yaml file to confirm the extension was added correctly under the node_extensions section.
5

Deploy Extension

Deploy your extension to make it available:
tenderly node-extensions deploy

​
Best Practices

Choose method names that clearly indicate what the extension does:
  • Good: extension_getVestedBalance, extension_calculateRewards
  • Avoid: extension_method1, extension_temp
Always provide meaningful descriptions that explain:
  • What the extension does
  • What parameters it expects
  • What data it returns
This helps team members understand the purpose of each extension.
Before initializing extensions, design and implement your Web3 Actions. This ensures your extension logic is ready before creating the RPC endpoint.
Follow a consistent naming convention across your extensions:
  • Use camelCase consistently
  • Group related methods with common prefixes
  • Example: extension_getBalance, extension_getRewards, extension_getStaked

​
Next Steps

Deploy Extensions

Learn how to deploy your configured extensions

Web3 Actions

Understand how to create and configure Web3 Actions

Configuration Reference

Complete node_extensions configuration reference

Extensions Overview

Learn more about Node Extensions concepts

Build docs developers (and LLMs) love

Get started for freeTalk to us