n8n-nodes-iota

[!IMPORTANT]
[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 package for the IOTA/Shimmer blockchain ecosystem. This package provides feeless blockchain automation with support for native tokens, NFTs, DIDs, encrypted data streams, and ShimmerEVM smart contracts.

Features

• Feeless Transactions: Send IOTA/SMR with zero fees
• Native Tokens: Create and manage L1 tokens via Foundries (IRC-30)
• NFTs: Mint, transfer, and manage L1 NFTs (IRC-27)
• Decentralized Identity: W3C DID standard with verifiable credentials
• Encrypted Streams: Machine-to-machine encrypted data channels
• Alias Outputs: Smart contract chain anchors and organizational accounts
• ShimmerEVM: EVM-compatible smart contract interactions
• Real-time Events: MQTT-based triggers for blockchain events
• Multi-network: IOTA Mainnet, Shimmer, Testnets, and Private Tangles

Supported Networks

Installation

Via npm (Recommended)

npm install n8n-nodes-iota

Manual Installation

1. Navigate to your n8n custom nodes directory:

   cd ~/.n8n/custom
   # Or for Docker: /home/node/.n8n/custom
   

2. Install the package:

   npm install n8n-nodes-iota
   

3. Restart n8n:

   n8n start
   

From Source

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

# Install dependencies
npm install

# Build the package
npm run build

# Link for local development
npm link

Credentials

IOTA Network

Configure your IOTA/Shimmer network connection:

• Network: Select from predefined networks or custom
• Node URL: IOTA node REST API endpoint
• Mnemonic: 24-word BIP39 seed phrase (stored securely)
• Stronghold Password: Optional encryption for key management
• MQTT URL: For real-time event subscriptions

ShimmerEVM

For smart contract interactions:

• RPC URL: ShimmerEVM JSON-RPC endpoint
• Private Key: Ethereum-style private key
• Chain ID: 148 (mainnet) or 1073 (testnet)

Chronicle

For historical data queries:

• API Endpoint: Chronicle permanode URL
• API Key: Optional authentication

Resources & Operations

Wallet

Transaction

Native Token (Foundry)

NFT

Identity (DID)

Streams

ShimmerEVM

Trigger Events

The IOTA Trigger node monitors real-time blockchain events:

• Funds Received: New outputs at an address
• Transaction Confirmed: Transaction reaches finality
• NFT Received: NFT transferred to address
• Alias State Changed: Alias output updated
• New Milestone: Network milestone issued
• Block Confirmed: Block reaches finality

Usage Examples

Send IOTA Tokens

{
  "resource": "transaction",
  "operation": "send",
  "recipientAddress": "iota1qp...",
  "amount": "1000000",
  "tag": "payment"
}

Mint an NFT

{
  "resource": "nft",
  "operation": "mintNft",
  "name": "My NFT",
  "description": "A unique digital asset",
  "uri": "ipfs://Qm...",
  "mediaType": "image/png"
}

Create a DID

{
  "resource": "identity",
  "operation": "createDidDocument",
  "controller": "self"
}

Monitor Address for Payments

Use the IOTA Trigger node:

1. Event: "Funds Received"
2. Address: Your Bech32 address
3. Options: Set minimum amount filter

IOTA Concepts

The Tangle

IOTA uses a Directed Acyclic Graph (DAG) called the Tangle instead of a traditional blockchain. This enables:

• Feeless transactions: No gas fees
• Parallel processing: High throughput
• Decentralization: No miners needed

Stardust Protocol

Current IOTA protocol version featuring:

• UTXO Model: Unspent Transaction Outputs
• Native Tokens: L1 token issuance via Foundries
• NFTs: L1 native non-fungible tokens
• Alias Outputs: Organizational accounts
• Storage Deposit: Rent to prevent ledger bloat

Storage Deposit

Outputs require a minimum deposit (rent) based on data size:

• Prevents ledger bloat
• Returned when output is consumed
• Calculated per virtual byte

Unlock Conditions

Outputs can have conditions that control spending:

• Timelock: Locked until timestamp
• Expiration: Reverts after timestamp
• Storage Deposit Return: Requires deposit return
• State Controller: Alias state changes
• Governor: Alias governance changes

Local Testing

Using Docker

# Pull n8n Docker image
docker pull n8nio/n8n

# Run with custom nodes mounted
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  -v $(pwd):/home/node/.n8n/custom/n8n-nodes-iota \
  n8nio/n8n

Using npx

# Start n8n with custom extensions path
N8N_CUSTOM_EXTENSIONS="./dist" npx n8n start

Build from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run linter
npm run lint

# Format code
npm run format

# Create distributable package
npm pack

Project Structure

n8n-nodes-iota/
├── credentials/
│   ├── IotaNetwork.credentials.ts
│   ├── ShimmerEvm.credentials.ts
│   └── Chronicle.credentials.ts
├── nodes/
│   └── Iota/
│       ├── Iota.node.ts
│       ├── IotaTrigger.node.ts
│       ├── iota.svg
│       ├── actions/
│       │   ├── wallet/
│       │   ├── transaction/
│       │   ├── output/
│       │   ├── nativeToken/
│       │   ├── nft/
│       │   ├── alias/
│       │   ├── streams/
│       │   ├── identity/
│       │   ├── stronghold/
│       │   ├── indexer/
│       │   ├── participation/
│       │   ├── shimmerEvm/
│       │   ├── node/
│       │   ├── block/
│       │   └── utility/
│       ├── transport/
│       │   ├── iotaClient.ts
│       │   ├── mqttClient.ts
│       │   ├── indexerClient.ts
│       │   ├── evmClient.ts
│       │   └── chronicleClient.ts
│       ├── constants/
│       │   ├── networks.ts
│       │   ├── protocols.ts
│       │   ├── schemas.ts
│       │   └── units.ts
│       └── utils/
│           ├── addressUtils.ts
│           ├── outputUtils.ts
│           ├── storageDeposit.ts
│           ├── streamsUtils.ts
│           └── unitConverter.ts
├── package.json
├── tsconfig.json
├── gulpfile.js
├── index.ts
├── README.md
└── LICENSE

Dependencies

Security

• Never share your mnemonic - 24-word seed phrase must be kept secret
• Use Stronghold - Secure encrypted storage for keys
• Validate addresses - Always verify Bech32 format and network HRP
• Test on testnet first - Use IOTA/Shimmer testnets before mainnet

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Resources

• IOTA Documentation
• Shimmer Documentation
• n8n Documentation
• IOTA SDK GitHub
• IRC-27 NFT Standard
• IRC-30 Token Standard

Author

Velocity BPA, LLC

• Website: velobpa.com
• Licensing: licensing@velobpa.com

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 also:

• LICENSE
• COMMERCIAL_LICENSE.md
• LICENSING_FAQ.md

Acknowledgments

• IOTA Foundation for the revolutionary DLT
• n8n for the amazing workflow automation platform
• The IOTA community for continuous innovation