n8n-nodes-xdc

[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 licensing@velobpa.com.

A comprehensive n8n community node for XDC Network - an enterprise-grade hybrid blockchain optimized for trade finance, international payments, and tokenized assets. Provides 10 resource categories and 50+ operations for complete blockchain integration.

---

Features

Resources

• Account - Balance queries, transaction history, token holdings, address validation
• Transaction - Send XDC, monitor transactions, estimate gas, get receipts
• XRC-20 Token - Token transfers, approvals, balances, allowances
• XRC-721 NFT - NFT metadata, transfers, collections, ownership
• Smart Contract - Read/write contract calls, ABI encoding, event logs
• Trade Finance - Document hashing, LC references, ISO 20022 validation
• Masternode - XDPoS staking, voting, rewards, epoch info
• DeFi - DEX swaps, liquidity pools, token prices
• Block - Block data, rewards, timestamps, epoch calculation
• Utility - Address conversion, unit conversion, hashing, signing

Trigger Events

• New blocks
• New epochs (every 900 blocks)
• Address transactions
• Token transfers

---

Installation

Community Nodes (Recommended)

1. Go to Settings → Community Nodes
2. Select Install
3. Enter n8n-nodes-xdc
4. Accept the risks and install

Manual Installation

cd ~/.n8n/nodes
npm install n8n-nodes-xdc

Development Installation

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

# Install dependencies
npm install

# Build
npm run build

# Link to n8n custom directory
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-xdc

# Restart n8n
n8n start

---

Credentials Setup

XDC Network Credentials

Field	Description	Required
Network	Mainnet (Chain 50) or Apothem Testnet (Chain 51)	Yes
RPC URL	Custom RPC endpoint (auto-filled based on network)	No
Private Key	Required for write operations (sending transactions)	No

XdcScan Credentials (Optional)

Field	Description	Required
Network	Mainnet or Apothem	Yes
API Key	BlocksScan API key for explorer data	Yes

---

Resources & Operations

Account

Operation	Description
Get Balance	Get XDC balance for an address
Get Token Balances	Get all token balances for an address
Get Transactions	Get transaction history for an address
Validate Address	Check if an address is valid

Transaction

Operation	Description
Send XDC	Send XDC to another address
Get History	Get transaction history
Get Receipt	Get transaction receipt by hash
Estimate Gas	Estimate gas for a transaction
Get Status	Check transaction status

Token (XRC-20)

Operation	Description
Get Balance	Get token balance for an address
Transfer	Transfer tokens to another address
Get Info	Get token metadata (name, symbol, decimals)
Approve	Approve spending allowance
Get Allowance	Check spending allowance

NFT (XRC-721)

Operation	Description
Get Metadata	Get NFT metadata and attributes
Get Owner	Get current owner of an NFT
Transfer	Transfer NFT to another address
Get Balance	Get NFT balance for an address
Get Tokens Owned	List all NFTs owned by an address

Smart Contract

Operation	Description
Call	Read data from a contract (no gas)
Execute	Write data to a contract (requires gas)
Get Events	Get contract event logs
Get ABI	Fetch contract ABI from explorer
Deploy	Deploy a new contract

Trade Finance

Operation	Description
Generate Hash	Create SHA256/Keccak256 hash of documents
Verify Hash	Verify document hash matches
Generate LC Reference	Generate Letter of Credit reference
Validate ISO 20022	Validate ISO 20022 message format

Masternode

Operation	Description
Get Candidates	List all masternode candidates
Get Masternode Info	Get details about a specific masternode
Get Epoch Info	Get current epoch information
Get Voter Info	Get voting information for an address
Calculate Rewards	Estimate staking rewards
Vote	Stake XDC with a masternode
Unvote	Withdraw stake from a masternode
Withdraw	Withdraw available rewards

DeFi

Operation	Description
Get XDC Price	Get current XDC/USD price
Get Token Price	Get token price in XDC or USD
Get Swap Quote	Get quote for token swap
Execute Swap	Execute token swap on DEX
Get Liquidity Pool	Get liquidity pool information

Block

Operation	Description
Get Block	Get block by number or hash
Get Latest Block	Get the most recent block
Get Block Transactions	Get all transactions in a block
Get Block Reward	Get mining reward for a block
Get Block By Timestamp	Find block closest to a timestamp

Utility

Operation	Description
Convert Units	Convert between wei, gwei, and XDC
Convert Address	Convert between xdc and 0x formats
Validate Address	Check if address is valid
Keccak256	Compute Keccak256 hash
Encode ABI	ABI encode function call
Decode ABI	ABI decode return data
Sign Message	Sign a message with private key
Verify Signature	Verify message signature
Get Network Status	Get network status and gas prices
Generate Wallet	Generate new wallet address

---

Trigger Node

The XDC Trigger node monitors blockchain events and triggers workflows.

Events

Event	Description
New Block	Triggers when a new block is mined
New Epoch	Triggers when a new epoch starts (every 900 blocks)
New Transaction	Triggers when a watched address receives a transaction
Token Transfer	Triggers when a token transfer occurs

Configuration

Parameter	Description
Event	The event type to monitor
Address	(Optional) Address to watch for transactions
Token Contract	(Optional) Token contract to monitor for transfers
Polling Interval	How often to check for new events (default: 30s)

---

Usage Examples

Get Account Balance

{
  "resource": "account",
  "operation": "getBalance",
  "address": "xdc1234567890abcdef1234567890abcdef12345678"
}

Send XDC

{
  "resource": "transaction",
  "operation": "sendXdc",
  "toAddress": "xdc1234567890abcdef1234567890abcdef12345678",
  "amount": "100"
}

Check Token Balance

{
  "resource": "token",
  "operation": "getBalance",
  "tokenAddress": "xdcTokenContractAddress...",
  "walletAddress": "xdcWalletAddress..."
}

Generate Trade Document Hash

{
  "resource": "tradeFinance",
  "operation": "generateHash",
  "documentContent": "Bill of Lading content...",
  "hashAlgorithm": "SHA256"
}

Vote for Masternode

{
  "resource": "masternode",
  "operation": "vote",
  "masternodeAddress": "xdcMasternodeAddress...",
  "stakeAmount": "10000"
}

---

XDC Network Concepts

Network Overview

• Consensus: XDPoS (Delegated Proof of Stake)
• Block Time: ~2 seconds
• Epoch Length: 900 blocks (~30 minutes)
• Masternodes: 108 validators
• Native Token: XDC
• Token Standards: XRC-20, XRC-721

Key Ecosystem Protocols

• Fathom Protocol - CDP/stablecoin (FXD)
• Plugin Oracle - Decentralized data feeds (PLI)
• XSwap/Globiance - DEX platforms
• XDC Subnet - Layer 2 scaling

Address Formats

XDC Network uses two address formats:

• xdc format: xdc1234567890abcdef1234567890abcdef12345678
• 0x format: 0x1234567890abcdef1234567890abcdef12345678

Both formats are interchangeable and represent the same address.

---

Networks

Network	Chain ID	RPC Endpoint	Explorer
Mainnet	50	https://rpc.xinfin.network	https://xdc.blocksscan.io
Apothem	51	https://rpc.apothem.network	https://apothem.blocksscan.io

---

Error Handling

The node includes comprehensive error handling:

• Network Errors: Automatic retry with exponential backoff
• Invalid Address: Clear error message with address format guidance
• Insufficient Funds: Detailed balance information
• Gas Estimation Failed: Suggested gas limit values
• Contract Errors: Decoded revert reasons when available

---

Security Best Practices

1. Private Key Storage: Never hardcode private keys. Use n8n credentials.
2. Testnet First: Always test workflows on Apothem testnet before mainnet.
3. Gas Limits: Set appropriate gas limits to prevent unexpected costs.
4. Address Validation: Always validate addresses before transactions.
5. Amount Verification: Double-check amounts before sending transactions.

---

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

---

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:
licensing@velobpa.com

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

---

Contributing

Contributions are welcome! Please ensure:

1. All code follows the existing style
2. Tests are added for new features
3. Documentation is updated
4. Licensing headers are included in new files

---

Support

• XDC Network
• XDC Documentation
• BlocksScan Explorer
• XDC Faucet (Testnet)

---

Acknowledgments

• XDC Network for the enterprise blockchain platform
• n8n for the workflow automation platform
• ethers.js for Ethereum/XDC library

---

Built with ❤️ for the XDC Network community