Node Extensions

Node Extensions provide a powerful way to create and deploy custom JSON-RPC endpoints that encapsulate functionalities specific to your dapp or protocol. This allows you to go beyond the elementary operations offered by the JSON-RPC standard.

Instead, you can create higher abstractions for interacting with the blockchain, capture your logic in one place, and make it easier to integrate it into UIs and backends. This way, you enable other dapps or protocols to achieve easier composability.

A Node Extension consists of Javascript/Typescript code that processes a JSON-RPC request at your custom endpoint. When you activate an extension in a project, it becomes available as a new Tenderly Node endpoint.

You can create a fully custom Node Extension in 4 ways:

• Build an extension from scratch, encapsulating your logic in Javascript/Typescript.
• Re-purpose a Web3 Action into an extension.
• Re-use an existing Node Extension coming from our open Node Extensions Library. You can contribute to the Node Extensions Library. This way, you can make reusability easier and enable other projects to integrate your abstractions.
• Use the Node Extensions Command Line Interface (CLI) to initialize and deploy your extensions. This tool is particularly useful for integrating Node Extensions into your development workflow and automating the deployment process​.

Creating a Node Extension

Let's explore the ways you can create a Node Extension:

• Creating a (private) custom Node Extension from scratch by providing JS/TS code that encapsulates your custom operations
• Creating a Node Extension from the Node Extension Library (from a public GitHub repo). This is a community-sourced library of extensions, making it easy to share extensions with others and enabling reusability and composability.
• Using an existing Web3 Action as the basis for a new Node Extension.
• Using the Node Extensions Command Line Interface (CLI) to easily initialize and deploy your extensions. This is a great way to manage your extensions programmatically, and fits seamlessly into automated workflows.

Creating a custom Node Extension from scratch

To create a new Node Extension, open the Tenderly Dashboard, click Node in the sidebar on the left, navigate to the Node Extensions tab, and click the Create Custom Extension button.

You can then define the custom JSON-RPC method name and write the JS/TS code that will be executed each time the method is called. After that, you can manually test your node extension.

Keep your code simple and easy to understand, and test thoroughly to ensure that your Node Extension is working correctly.

Creating a Node Extension from a Web3 Action

If you've already created a Web3 Action with a non-authenticated webhook trigger type, you can use its source code as the function of your Node Extension. To do this, simply navigate to the Node Extensions tab in the Tenderly Dashboard and click the Create Custom Extension button.

From there, select the relevant Web3 Action from the dropdown menu. This automatically populates the function field with the Javascript/Typescript code from your Web3 Action.

After that, you can manually test your node extension.

Creating a Node Extension from the Node Extension Library

To help you get started, you can use the Node Extension Library to enable a ready-made node extension in one click. You can use these ready-made extensions to get inspired and start experimenting with your own extensions.

To activate a Library Node Extension, navigate to the Node Extensions tab in the Tenderly Dashboard and click the Add From Library button. When you open the modal, you'll see the list of all publicly available Node Extensions. Each template has a GitHub link to the source code.

Next, click the Activate button to set up a pre-defined Node Extension with its corresponding Web3 Action that represents the source code of the extension.

After that, you can manually test your node extension.

After enabling Node Extensions, you'll be directed to the Node Extension page where you can view all of your enabled extensions. Each card displays the extension name, method name, description, author, and clickable icon.

If you created a Node Extension using a library example, a GitHub icon with a link to its source code will be displayed. If it's a custom Node Extension, the Web3 Action with the corresponding status and source code will be linked.

Creating a Node Extension from CLI

The Tenderly CLI now supports operations related to Node Extensions. This allows you to extend the functionalities of the Tenderly node and create custom JSON-RPC endpoints that encapsulate functionalities specific to your dapp or protocol from the command line.

Initializing Node Extensions

The tenderly node-extensions init command initializes the node_extensions section of your tenderly.yaml file. It takes the following arguments:

• name: Specifies the extension name.
• description: Specifies the extension description.
• methodName: Specifies the extension method name. Note that all Node Extensions method names must start with the extension_ prefix​​.

tenderly node-extensions init --name "extension-name" --description "extension description" --methodName "extension_test"

After running this command, you'll get something like this:

account_id: ''
actions:
  ACCOUNT_NAME/PROJECT_SLUG:
    runtime: v2
    sources: actions
    specs:
      example:
        description: Non-authenticated webhook example
        function: example:nodeExtensionFn
        trigger:
          type: webhook
          webhook:
            authenticated: false
node_extensions:
  ACCOUNT_NAME/PROJECT_SLUG:
    specs:
      extension-name:
        description: extension description
        method: extension_test
        action: example
project_slug: ''

import { ActionFn, Context, Event, ExtensionEvent } from '@tenderly/actions';
 
export const nodeExtensionFn: ActionFn = async (context: Context, event: Event) => {
  const extensionEvent = event as ExtensionEvent;
  console.log({ extensionEvent });
  return extensionEvent;
};

The command first validates the provided methodName and then prompts you to select one action from a list of those eligible for extensions, presented in the format account/project:action. The list only includes actions that aren't already used by other extensions in the tenderly.yaml file. If no actions are eligible for extensions, or if all eligible actions are already used by other extensions, the command will return an error. After an action is selected, the command checks if the chosen extension method name is already used by another extension in the same account/project. If it isn't, the extension is added to the tenderly.yaml file.

Deploying Node Extensions

tenderly node-extensions deploy

The tenderly node-extensions deploy command deploys extensions specified in the tenderly.yaml file. It accepts the following arguments:

• account: Specifies the account for which the extension is defined in the tenderly.yaml file.
• project: Specifies the project for which the extension is defined in the tenderly.yaml file.
• extensionName: Specifies the extension in the provided account/project that should be deployed.

If no arguments are provided, the command will attempt to deploy all extensions defined in the tenderly.yaml file. If any of these extension deployments fail, the command will print out the failure reasons and continue with the deployment.

Testing a Node Extension

After creating a Node Extension, you should test it to make sure it's working properly. To do this, click the Test button within the Node Extension card to open the Test Node Extension modal.

The modal contains a JSON-RPC Request Builder, which you can use to create a JSON input payload for your custom method name. This payload should contain any necessary data or parameters that your Node Extension needs to execute correctly.

Once you've created your JSON input payload, click the Send button to execute your Node Extension. You'll see the request and response previews in the modal, showing you the exact data that was sent and received.

Editing Node Extensions

Node Extensions made from the Node Extension Library cannot be edited. However, if the extension is custom-made, it can be edited in two ways:

• If you created the extension using the Tenderly CLI, the extension needs to be redeployed from the CLI.
• If you created the extension from the Tenderly Dashboard, you can edit the extension directly from the Dashboard.

You can see the connected Web3 Action when you open the extension card and go to the single node extension page view. Clicking on the connected Web3 Action takes you to the Web3 Action page. It's important to note that any changes to the extension will require changes to the connected Web3 Action.

Activating and deactivating Node Extensions

You can activate or deactivate Node Extensions depending on your needs. Here's what you need to know about the activation and deactivation process:

Custom Node Extensions

If you create a custom Node Extension, deactivation simply pauses its execution. This means that the extension won't be executed when its corresponding method name is called. To reactivate the Node Extension, simply click the Activate button.

Library Node Extensions

If you create a Node Extension from the Library, deactivation permanently deletes the extension and its associated Web3 Action from your list. This cannot be undone, so make sure you want to permanently delete the Node Extension before deactivating it.

Node Extension Page

Opening an extension card takes you to the Node Extension page, where you can view detailed information about the extension. The information includes the source code of the extension, its name, description, when it was created, and which Web3 Action is linked to it.

If you no longer need a Node Extension, you can delete it from the Node Extension page. Simply click the Delete button to permanently remove the extension from your Tenderly account.

Contributing to the Node Extension Library

We welcome contributions to our public GitHub repository, which contains Node Extension examples and extension starter code. By contributing to our open-source community library, you can help others learn from your work and potentially inspire new use cases. Additionally, it becomes easier to share extensions among different projects and protocols, making integrations and composition easier.

How to contribute

To contribute to our repository, simply open a pull request with your node extension source code and a detailed description of its use case. We encourage you to include any relevant information or resources that can help others understand and use your node extension. This can include documentation, diagrams, or even video tutorials.

Once your pull request is reviewed and approved, your node extension will be added to our repository and made available for others to use and build upon. You will also be credited as the author of the node extension, which can help you build your reputation within the community.