n8n-nodes-vechain

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact [email protected].

A comprehensive n8n community node package for interacting with the VeChain blockchain. This node provides full support for VET/VTHO transfers, VIP-180 tokens, VIP-181 NFTs, smart contracts, multi-clause transactions, fee delegation, and enterprise features.

Features

VeChain Blockchain Support

• Dual Token Model: VET (value) + VTHO (energy/gas)
• Multi-Clause Transactions: Batch multiple operations in a single atomic transaction
• Fee Delegation (VIP-191): Third-party gas payment support
• PoA 2.0 Consensus: 101 authority masternodes with ~10s block time

Token Standards

• VIP-180: Fungible token standard (similar to ERC-20)
• VIP-181: Non-fungible token standard (similar to ERC-721)

Networks Supported

• Mainnet: Production VeChain network
• Testnet: Test network for development
• Thor Solo: Local development node
• Custom: Connect to any VeChain-compatible node

Installation

Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Click Install
4. Enter n8n-nodes-vechain
5. Click Install

Manual Installation

# Navigate to your n8n installation
cd ~/.n8n

# Install the package
npm install n8n-nodes-vechain

# Restart n8n

Development Installation

# Clone the repository
git clone https://github.com/Velocity-BPA/n8n-nodes-vechain.git
cd n8n-nodes-vechain

# Install dependencies
npm install

# Build the project
npm run build

# Create symlink to n8n custom nodes directory
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-vechain

# Restart n8n
n8n start

Credentials Setup

VeChain Network Credentials

Configure your network connection and wallet:

| Field | Description | |-------|-------------| | Network | Select mainnet, testnet, solo, or custom | | Node URL | Custom node URL (for custom network) | | Private Key | Your wallet private key (hex format) | | Delegator URL | Optional fee delegation service URL |

VeChain API Credentials

For enhanced features and analytics:

| Field | Description | |-------|-------------| | API Type | VeChainStats, ToolChain, or VeExplorer | | API Key | Your API key for the selected service |

Fee Delegation Credentials

For gas-free transactions:

| Field | Description | |-------|-------------| | Delegation Type | Service, Self-Sponsor, or VeChain Energy | | Service URL | Delegation service endpoint | | Sponsor Private Key | Key for self-sponsoring |

Resources & Operations

VeChain Node (Action Node)

Account Operations

• Get Account Info
• Get VET Balance
• Get VTHO Balance
• Validate Address
• Calculate VTHO Generation
• Check if Contract

Transaction Operations

• Send VET
• Send VTHO
• Get Transaction
• Get Receipt
• Get Status
• Estimate Gas
• Build Transaction
• Sign Transaction
• Send Raw Transaction
• Multi-Clause Transaction
• Simulate Transaction

VET Operations

• Get Balance
• Transfer VET
• Multi-Transfer VET
• Estimate Transfer Fee

VTHO Operations

• Get Balance
• Transfer VTHO
• Get Total Supply
• Get Total Burned
• Approve Spending
• Get Allowance
• Calculate Generation

VIP-180 Token Operations

• Get Token Info
• Get Balance
• Transfer
• Approve
• Get Allowance
• Transfer From
• Get Total Supply

VIP-181 NFT Operations

• Get Collection Info
• Get Owner
• Get Balance
• Get Token URI
• Get Tokens by Owner
• Transfer
• Safe Transfer
• Approve
• Set Approval For All
• Get Approved
• Is Approved For All

Smart Contract Operations

• Read (Call)
• Write (Send)
• Deploy
• Get Code
• Get Storage
• Encode Function
• Decode Result
• Simulate
• Estimate Gas

Block Operations

• Get Block
• Get Best Block
• Get Finalized Block
• Get Genesis Block
• Get Block Transactions
• Get Block Height
• Check Finality
• Get Block Range

Utility Operations

• Convert VET Units
• Convert VTHO Units
• Validate Address
• Generate Keypair
• Generate from Mnemonic
• Get Address from Private Key
• Sign Message
• Verify Signature
• Hash Data
• Get Block Ref
• Get Network Info
• Calculate VTHO Cost
• Checksum Address

Trigger Node

VeChain Trigger

Monitor blockchain events in real-time:

• New Block: Trigger on new blocks
• Transaction Confirmed: Monitor specific transactions
• VET Transfer: Watch VET movements
• VTHO Transfer: Watch VTHO movements
• VIP-180 Transfer: Monitor token transfers
• VIP-181 Transfer: Monitor NFT transfers
• Contract Event: Watch for smart contract events

Usage Examples

Send VET

// Configuration
{
  "resource": "vet",
  "operation": "transfer",
  "toAddress": "0x...",
  "amount": "100"
}

Get Token Balance

// Configuration
{
  "resource": "vip180",
  "operation": "getBalance",
  "contractAddress": "0x0000000000000000000000000000456E65726779",
  "ownerAddress": "0x..."
}

Multi-Clause Transaction

// Send VET to multiple recipients in one transaction
{
  "resource": "vet",
  "operation": "multiTransfer",
  "recipients": [
    { "address": "0x...", "amount": "10" },
    { "address": "0x...", "amount": "20" },
    { "address": "0x...", "amount": "30" }
  ]
}

Read Smart Contract

// Call a contract function
{
  "resource": "contract",
  "operation": "read",
  "contractAddress": "0x...",
  "abi": "[...]",
  "functionName": "balanceOf",
  "parameters": "[\"0x...\"]"
}

Calculate VTHO Generation

// Calculate VTHO generated by VET holdings
{
  "resource": "account",
  "operation": "calculateVthoGeneration",
  "vetAmount": "1000000",
  "timePeriod": "month"
}

VeChain Concepts

Dual Token Model

VeChain uses two tokens:

• VET (VeChain Token): The value token for transfers and staking
• VTHO (VeThor Token): The energy token used for gas fees

VET generates VTHO over time at a rate of 0.000432 VTHO per VET per day (5×10⁻⁹ per second).

Multi-Clause Transactions

Unlike Ethereum, VeChain supports multiple operations in a single transaction:

• Send to multiple recipients
• Interact with multiple contracts
• Mix different operation types
• Atomic execution (all or nothing)

Fee Delegation (VIP-191)

Third parties can pay gas fees on behalf of users:

• Improves user experience
• Enables gas-free applications
• Supports enterprise use cases

Block Finality

VeChain PoA 2.0 provides:

• ~10 second block time
• ~12 blocks to finality (~120 seconds)
• Two-phase commit confirmation
• 101 authority masternodes

Networks

| Network | Chain Tag | Node URL | |---------|-----------|----------| | Mainnet | 0x4a (74) | https://mainnet.veblocks.net | | Testnet | 0x27 (39) | https://testnet.veblocks.net | | Thor Solo | 0xf6 (246) | http://localhost:8669 |

Error Handling

Common Errors

"Invalid private key"

• Ensure your private key is in hex format
• Remove the 0x prefix if present
• Key should be 64 characters (32 bytes)

"Insufficient VTHO"

• Check your VTHO balance
• VTHO is required for gas fees
• VET generates VTHO over time

"Transaction reverted"

• Check contract requirements
• Verify you have sufficient balances
• Use simulate before sending

"Network timeout"

• Check node URL is correct
• Try a different node
• Check network connectivity

Security Best Practices

1. Never share private keys - Store them securely
2. Use testnet for development - Test thoroughly before mainnet
3. Validate addresses - Always validate before sending
4. Simulate transactions - Use simulate before sending value
5. Check balances - Ensure sufficient VET and VTHO

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in watch mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: [email protected]

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• VeChain Foundation - For the VeChain blockchain
• n8n - For the workflow automation platform
• thor-devkit - VeChain SDK

Changelog

v1.0.0

• Initial release
• Full VeChain blockchain support
• VET/VTHO operations
• VIP-180 token support
• VIP-181 NFT support
• Smart contract interactions
• Multi-clause transactions
• Fee delegation support
• Block and event monitoring
• Utility functions