tenderly node-extensions deploy

Overview

The deploy command deploys node extensions to your Tenderly gateway, making your custom RPC methods available for use. You can deploy a single extension or all extensions configured in your tenderly.yaml file.

tenderly node-extensions deploy [flags]

Prerequisites

Before deploying extensions, ensure you have:

Authenticated with Tenderly
```
tenderly login
```
Initialized at least one extension in your tenderly.yaml
```
tenderly node-extensions init
```
An active gateway configured for your project

Deployment will fail if you don’t have a gateway configured for your project. Contact Tenderly support to set up a gateway.

Deployment Modes

The deploy command supports two modes:

Deploy All Extensions

Deploy all extensions configured in tenderly.yaml:

tenderly node-extensions deploy

This mode:

Reads all projects and extensions from your configuration
Deploys each extension to its respective project’s gateway
Reports success or failure for each extension

Deploy Single Extension

Deploy a specific extension by providing all required flags:

tenderly node-extensions deploy \
  --account my-account \
  --project my-project \
  --extensionName my-extension

When deploying a single extension, all three flags (--account, --project, --extensionName) are required.

Flags

--account

string

The account slug where the extension will be deployed. Required when deploying a single extension.

--account my-account

--project

string

The project slug where the extension will be deployed. Required when deploying a single extension.

--project my-project

--extensionName

string

Name of the specific extension to deploy (as defined in tenderly.yaml). Required when deploying a single extension.

--extensionName token-balance

Examples

Deploy All Extensions

Deploy all configured extensions across all projects:

tenderly node-extensions deploy

Output:

Extension token-balance deployed successfully.
Extension portfolio-aggregator deployed successfully.
Extension validate-tx deployed successfully.

Deploy Single Extension

Deploy only a specific extension:

tenderly node-extensions deploy \
  --account acme-corp \
  --project defi-protocol \
  --extensionName token-balance

Output:

Extension token-balance deployed successfully.

Deploy from CI/CD Pipeline

Deploy extensions as part of your automated deployment:

.github/workflows/deploy.yml

name: Deploy Extensions

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Tenderly CLI
        run: curl https://raw.githubusercontent.com/Tenderly/tenderly-cli/master/scripts/install-linux.sh | sh
      
      - name: Login to Tenderly
        run: tenderly login --authentication-method access-key --access-key ${{ secrets.TENDERLY_ACCESS_KEY }}
      
      - name: Deploy Extensions
        run: tenderly node-extensions deploy

Validation

Before deploying, the command validates each extension:

Method Name Validation

Ensures the method name follows the required pattern:

^extension_[a-z][A-Za-z0-9]{2,}(?:[A-Z][a-z0-9]+)*$

Error:

Error deploying extension my-extension
	Invalid extension method name

Method Name Availability

Checks that the method name isn’t already used by another extension: Error:

Error deploying extension my-extension
	Extension method name is already in use

Action Existence

Verifies the referenced action exists in the project: Error:

Error deploying extension my-extension
	Action does not exist

Action Availability

Confirms the action isn’t already used by another extension: Error:

Error deploying extension my-extension
	Action is already in use

Error Handling

Missing Required Flags

When deploying a single extension, all flags must be provided:

$ tenderly node-extensions deploy --account my-account

Error deploying extension: missing required flag(s): project, extensionName

Solution: Provide all three flags or omit them all to deploy all extensions.

Extension Not Found in Config

If the specified extension doesn’t exist in tenderly.yaml:

Error deploying extension: couldn't read extension config from tenderly.yaml

Solution: Verify the extension name matches what’s in your configuration:

tenderly.yaml

node_extensions:
  my-account/my-project:
    specs:
      token-balance:  # This is the extension name
        method: extension_getTokenBalance
        action: balance-action

No Gateway Found

If the project doesn’t have a gateway configured:

Error deploying extensions: No gateway found for project "my-account/my-project".

Solution: Contact Tenderly support to set up a gateway for your project.

Multiple Validation Failures

Multiple validation errors are reported together:

Error deploying extension my-extension
	Invalid extension method name
	Action is already in use

Deployment Process

Understanding what happens during deployment:

Read Configuration

The CLI reads extension configurations from your tenderly.yaml file.

Fetch Project Data

For each project, the CLI fetches:

Gateway information
Existing actions
Currently deployed extensions

Validate Extensions

Each extension is validated:

Method name format
Method name uniqueness
Action existence
Action availability

Deploy to Gateway

Valid extensions are deployed to the project’s gateway, creating the custom RPC endpoint.

Report Results

Success or failure is reported for each extension.

Using Deployed Extensions

Once deployed, your extensions are available via your Tenderly gateway:

JavaScript/TypeScript (ethers.js)

import { ethers } from 'ethers';

const provider = new ethers.providers.JsonRpcProvider(
  'https://your-gateway-url.tenderly.co'
);

// Call your custom RPC method
const result = await provider.send('extension_getTokenBalance', [
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // USDC
]);

console.log('Custom balance:', result);

Web3.js

const Web3 = require('web3');

const web3 = new Web3('https://your-gateway-url.tenderly.co');

// Call your custom RPC method
const result = await web3.currentProvider.send(
  {
    jsonrpc: '2.0',
    method: 'extension_getTokenBalance',
    params: [
      '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
    ],
    id: 1
  },
  (error, response) => {
    console.log('Custom balance:', response.result);
  }
);

cURL

Test your extension with cURL:

curl -X POST https://your-gateway-url.tenderly.co \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "extension_getTokenBalance",
    "params": [
      "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    ],
    "id": 1
  }'

Best Practices

Test Before Deploying

Test your Web3 Actions thoroughly before deploying extensions:

Deploy the action first
Test the webhook endpoint directly
Verify the response format
Then deploy the extension

Use Version Control

Commit your tenderly.yaml configuration changes before deploying:

git add tenderly.yaml
git commit -m "Add new extension: token-balance"
tenderly node-extensions deploy

Deploy in Stages

For multiple extensions, consider deploying one at a time first:

# Deploy and test one extension
tenderly node-extensions deploy \
  --account my-account \
  --project my-project \
  --extensionName extension-1

# After verifying it works, deploy all
tenderly node-extensions deploy

Monitor Deployments

Keep track of deployment results, especially in CI/CD:

Check exit codes in automated pipelines
Log deployment outputs
Set up notifications for deployment failures

Document Gateway URLs

Keep your gateway URLs documented and secure:

Store them in environment variables
Don’t commit them to public repositories
Share them securely with team members

Troubleshooting

Extension deployed but not working

If deployment succeeds but the extension isn’t callable:

Verify your gateway URL is correct
Check the action is properly deployed
Test the webhook endpoint directly
Ensure the action’s webhook trigger is not authenticated

Action validation failures

If the action fails validation:

Confirm the action exists in your Tenderly dashboard
Verify it has a webhook trigger
Check that authenticated: false is set
Ensure it’s not used by another extension

Gateway not found errors

If you get “No gateway found” errors:

Contact Tenderly support to enable gateway access
Verify your account and project slugs are correct
Check you have appropriate permissions

Next Steps

Initialize Extensions

Learn how to create new extensions

Web3 Actions

Build and test your action logic

Extensions Overview

Understand Node Extensions concepts

Configuration Reference

Complete configuration reference

Getting Started

Core Commands

Contract Management

Actions

DevNets

Extensions

Configuration

Guides

​Overview

​Prerequisites

​Deployment Modes

​Deploy All Extensions

​Deploy Single Extension

​Flags

​Examples

​Deploy All Extensions

​Deploy Single Extension

​Deploy from CI/CD Pipeline

​Validation

​Method Name Validation

​Method Name Availability

​Action Existence

​Action Availability

​Error Handling

​Missing Required Flags

​Extension Not Found in Config

​No Gateway Found

​Multiple Validation Failures

​Deployment Process

​Using Deployed Extensions

​JavaScript/TypeScript (ethers.js)

​Web3.js

​cURL

​Best Practices

​Troubleshooting

​Next Steps

Initialize Extensions

Web3 Actions

Extensions Overview

Configuration Reference

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Modes

Deploy All Extensions

Deploy Single Extension

Flags

Examples

Deploy All Extensions

Deploy Single Extension

Deploy from CI/CD Pipeline

Validation

Method Name Validation

Method Name Availability

Action Existence

Action Availability

Error Handling

Missing Required Flags

Extension Not Found in Config

No Gateway Found

Multiple Validation Failures

Deployment Process

Using Deployed Extensions

JavaScript/TypeScript (ethers.js)

Web3.js

cURL

Best Practices

Troubleshooting

Next Steps