n8n-nodes-iota 1.0.0

package/LICENSE

@@ -0,0 +1,46 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab.
+
+Licensor:
+Velocity BPA, LLC
+https://velobpa.com
+
+Licensed Work:
+This repository and all source code, documentation, and associated artifacts
+contained herein, including all n8n community nodes published by Velocity BPA.
+
+Additional Use Grant:
+You may use, modify, and run the Licensed Work free of charge for:
+- Personal use
+- Educational use
+- Research use
+- Internal business use, provided such use does not involve resale,
+  redistribution, or offering the Licensed Work as part of a commercial
+  product or service.
+
+Commercial Use Restriction:
+Commercial Use of the Licensed Work is prohibited without a valid
+Commercial License issued by the Licensor.
+
+Commercial Use includes, but is not limited to:
+- Use of the Licensed Work within any Software-as-a-Service (SaaS),
+  Platform-as-a-Service (PaaS), or hosted application that is sold,
+  licensed, or monetized in any form
+- Offering the Licensed Work as part of a managed services engagement
+- Bundling or redistributing the Licensed Work with a paid product
+- Reselling, sublicensing, or white-labeling the Licensed Work
+- Embedding the Licensed Work into any commercial automation platform,
+  integration product, or solution offering
+
+Change Date:
+January 1, 2030
+
+Change License:
+Apache License, Version 2.0
+
+For commercial licensing inquiries:
+licensing@velobpa.com
+
+Business Source License 1.1 full text:
+https://mariadb.com/bsl11/

package/README.md

@@ -0,0 +1,407 @@
+# 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.
+
+![IOTA](https://img.shields.io/badge/IOTA-Stardust-0fc1b7?style=flat-square&logo=iota)
+![Shimmer](https://img.shields.io/badge/Shimmer-EVM-25f4ee?style=flat-square)
+![n8n](https://img.shields.io/badge/n8n-Community%20Node-ff6d5a?style=flat-square&logo=n8n)
+![License](https://img.shields.io/badge/License-BUSL%201.1-blue?style=flat-square)
+
+## 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
+
+| Network | HRP | Coin Type | Status |
+|---------|-----|-----------|--------|
+| IOTA Mainnet | `iota` | 4218 | ✅ Production |
+| Shimmer Mainnet | `smr` | 4219 | ✅ Production |
+| IOTA Testnet | `atoi` | 4218 | ✅ Testing |
+| Shimmer Testnet | `rms` | 4219 | ✅ Testing |
+| Private Tangle | Custom | Custom | ✅ Development |
+
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install n8n-nodes-iota
+```
+
+### Manual Installation
+
+1. Navigate to your n8n custom nodes directory:
+   ```bash
+   cd ~/.n8n/custom
+   # Or for Docker: /home/node/.n8n/custom
+   ```
+
+2. Install the package:
+   ```bash
+   npm install n8n-nodes-iota
+   ```
+
+3. Restart n8n:
+   ```bash
+   n8n start
+   ```
+
+### From Source
+
+```bash
+# 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
+| Operation | Description |
+|-----------|-------------|
+| Get Balance | Get total wallet balance |
+| Generate Address | Create new receiving address |
+| Get Transaction History | List past transactions |
+| Sync Wallet | Synchronize with Tangle |
+| Validate Address | Check Bech32 address validity |
+
+### Transaction
+| Operation | Description |
+|-----------|-------------|
+| Send | Basic IOTA/SMR transfer |
+| Send Multiple | Multi-recipient transaction |
+| Get Transaction | Retrieve transaction details |
+| Get Status | Check confirmation status |
+
+### Native Token (Foundry)
+| Operation | Description |
+|-----------|-------------|
+| Create Foundry | Initialize token issuance |
+| Mint Tokens | Create new tokens |
+| Melt Tokens | Burn/destroy tokens |
+| Send Tokens | Transfer native tokens |
+| Get Token Info | IRC-30 metadata |
+
+### NFT
+| Operation | Description |
+|-----------|-------------|
+| Mint NFT | Create new NFT (IRC-27) |
+| Transfer NFT | Send NFT to address |
+| Burn NFT | Destroy NFT permanently |
+| Get NFT | Retrieve NFT details |
+| Get Collection | List NFTs by issuer |
+
+### Identity (DID)
+| Operation | Description |
+|-----------|-------------|
+| Create DID | New decentralized identity |
+| Resolve DID | Fetch DID Document |
+| Create Credential | Issue verifiable credential |
+| Verify Credential | Validate VC signature |
+| Revoke Credential | Mark credential as revoked |
+
+### Streams
+| Operation | Description |
+|-----------|-------------|
+| Create Channel | Initialize encrypted channel |
+| Publish Message | Send encrypted message |
+| Subscribe | Request channel access |
+| Read Messages | Decrypt and read messages |
+
+### ShimmerEVM
+| Operation | Description |
+|-----------|-------------|
+| Get Balance | EVM account balance |
+| Send Transaction | Transfer SMR on EVM |
+| Call Contract | Read contract state |
+| Execute Contract | Write to contract |
+| Deploy Contract | Deploy new contract |
+
+## 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
+```json
+{
+  "resource": "transaction",
+  "operation": "send",
+  "recipientAddress": "iota1qp...",
+  "amount": "1000000",
+  "tag": "payment"
+}
+```
+
+### Mint an NFT
+```json
+{
+  "resource": "nft",
+  "operation": "mintNft",
+  "name": "My NFT",
+  "description": "A unique digital asset",
+  "uri": "ipfs://Qm...",
+  "mediaType": "image/png"
+}
+```
+
+### Create a DID
+```json
+{
+  "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
+
+```bash
+# 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
+
+```bash
+# Start n8n with custom extensions path
+N8N_CUSTOM_EXTENSIONS="./dist" npx n8n start
+```
+
+## Build from Source
+
+```bash
+# 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
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| @iota/sdk | ^1.1.4 | IOTA SDK for Tangle interactions |
+| ethers | ^6.9.0 | ShimmerEVM smart contracts |
+| mqtt | ^5.3.0 | Real-time event subscriptions |
+| axios | ^1.6.2 | REST API client |
+
+## 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](https://wiki.iota.org/)
+- [Shimmer Documentation](https://wiki.shimmer.network/)
+- [n8n Documentation](https://docs.n8n.io/)
+- [IOTA SDK GitHub](https://github.com/iotaledger/iota-sdk)
+- [IRC-27 NFT Standard](https://github.com/iotaledger/tips/blob/main/tips/TIP-0027/tip-0027.md)
+- [IRC-30 Token Standard](https://github.com/iotaledger/tips/blob/main/tips/TIP-0030/tip-0030.md)
+
+## Author
+
+**Velocity BPA, LLC**
+- Website: [velobpa.com](https://velobpa.com)
+- Licensing: [licensing@velobpa.com](mailto: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](LICENSE)
+- [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md)
+- [LICENSING_FAQ.md](LICENSING_FAQ.md)
+
+## Acknowledgments
+
+- [IOTA Foundation](https://www.iota.org/) for the revolutionary DLT
+- [n8n](https://n8n.io/) for the amazing workflow automation platform
+- The IOTA community for continuous innovation

package/dist/credentials/Chronicle.credentials.d.ts

@@ -0,0 +1,23 @@
+import { ICredentialType, INodeProperties, ICredentialTestRequest } from 'n8n-workflow';
+/**
+ * Chronicle Credentials
+ *
+ * Chronicle is IOTA's permanode solution that stores
+ * the complete history of the Tangle. Unlike regular nodes
+ * that may prune old data, Chronicle maintains all historical
+ * transactions and outputs for querying.
+ *
+ * Use cases:
+ * - Historical transaction queries
+ * - Output history tracking
+ * - Analytics and reporting
+ * - Audit trails
+ */
+export declare class Chronicle implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    test: ICredentialTestRequest;
+}
+//# sourceMappingURL=Chronicle.credentials.d.ts.map

package/dist/credentials/Chronicle.credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Chronicle.credentials.d.ts","sourceRoot":"","sources":["../../credentials/Chronicle.credentials.ts"],"names":[],"mappings":"AAOA,OAAO,EACN,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,eAAe;IAChD,IAAI,SAAe;IACnB,WAAW,SAA2B;IACtC,gBAAgB,SAAsC;IACtD,UAAU,EAAE,eAAe,EAAE,CAyC3B;IAEF,IAAI,EAAE,sBAAsB,CAS1B;CACF"}

package/dist/credentials/Chronicle.credentials.js

@@ -0,0 +1,84 @@
+"use strict";
+/*
+ * Copyright (c) Velocity BPA, LLC
+ * Licensed under the Business Source License 1.1
+ * Commercial use requires a separate commercial license.
+ * See LICENSE file for details.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Chronicle = void 0;
+/**
+ * Chronicle Credentials
+ *
+ * Chronicle is IOTA's permanode solution that stores
+ * the complete history of the Tangle. Unlike regular nodes
+ * that may prune old data, Chronicle maintains all historical
+ * transactions and outputs for querying.
+ *
+ * Use cases:
+ * - Historical transaction queries
+ * - Output history tracking
+ * - Analytics and reporting
+ * - Audit trails
+ */
+class Chronicle {
+    constructor() {
+        this.name = 'chronicle';
+        this.displayName = 'Chronicle (Permanode)';
+        this.documentationUrl = 'https://wiki.iota.org/chronicle/';
+        this.properties = [
+            {
+                displayName: 'Chronicle Endpoint',
+                name: 'chronicleUrl',
+                type: 'string',
+                default: 'https://chronicle.testnet.shimmer.network',
+                placeholder: 'https://chronicle.testnet.shimmer.network',
+                required: true,
+                description: 'URL of the Chronicle permanode API',
+            },
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                description: 'API key for Chronicle access (if required by the provider)',
+            },
+            {
+                displayName: 'Request Timeout (ms)',
+                name: 'timeout',
+                type: 'number',
+                default: 30000,
+                description: 'Request timeout in milliseconds (historical queries can be slow)',
+            },
+            {
+                displayName: 'Max Results Per Query',
+                name: 'maxResults',
+                type: 'number',
+                default: 1000,
+                description: 'Maximum number of results to return per query',
+            },
+            {
+                displayName: 'Include Metadata',
+                name: 'includeMetadata',
+                type: 'boolean',
+                default: true,
+                description: 'Include additional metadata in query results',
+            },
+        ];
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.chronicleUrl}}',
+                url: '/api/core/v2/info',
+                method: 'GET',
+                headers: {
+                    'Authorization': '={{$credentials.apiKey ? "Bearer " + $credentials.apiKey : ""}}',
+                },
+            },
+        };
+    }
+}
+exports.Chronicle = Chronicle;
+//# sourceMappingURL=Chronicle.credentials.js.map

package/dist/credentials/Chronicle.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Chronicle.credentials.js","sourceRoot":"","sources":["../../credentials/Chronicle.credentials.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAQH;;;;;;;;;;;;;GAaG;AACH,MAAa,SAAS;IAAtB;QACC,SAAI,GAAG,WAAW,CAAC;QACnB,gBAAW,GAAG,uBAAuB,CAAC;QACtC,qBAAgB,GAAG,kCAAkC,CAAC;QACtD,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,oBAAoB;gBACjC,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,2CAA2C;gBACpD,WAAW,EAAE,2CAA2C;gBACxD,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,oCAAoC;aACjD;YACD;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE;oBACZ,QAAQ,EAAE,IAAI;iBACd;gBACD,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,4DAA4D;aACzE;YACD;gBACC,WAAW,EAAE,sBAAsB;gBACnC,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,KAAK;gBACd,WAAW,EAAE,kEAAkE;aAC/E;YACD;gBACC,WAAW,EAAE,uBAAuB;gBACpC,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,IAAI;gBACb,WAAW,EAAE,+CAA+C;aAC5D;YACD;gBACC,WAAW,EAAE,kBAAkB;gBAC/B,IAAI,EAAE,iBAAiB;gBACvB,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI;gBACb,WAAW,EAAE,8CAA8C;aAC3D;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,gCAAgC;gBACzC,GAAG,EAAE,mBAAmB;gBACxB,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACR,eAAe,EAAE,iEAAiE;iBAClF;aACD;SACD,CAAC;IACH,CAAC;CAAA;AAzDD,8BAyDC"}

package/dist/credentials/IotaNetwork.credentials.d.ts

@@ -0,0 +1,22 @@
+import { ICredentialType, INodeProperties, ICredentialTestRequest } from 'n8n-workflow';
+/**
+ * IOTA Network Credentials
+ *
+ * Supports multiple IOTA/Shimmer networks:
+ * - IOTA Mainnet: Production network for IOTA token
+ * - Shimmer Mainnet: Canary network with EVM support
+ * - IOTA Testnet: Testing network for IOTA
+ * - Shimmer Testnet: Public testnet with faucet
+ * - Private Tangle: Custom network deployments
+ *
+ * The Tangle is a DAG (Directed Acyclic Graph) structure,
+ * not a traditional blockchain. Transactions are feeless.
+ */
+export declare class IotaNetwork implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    test: ICredentialTestRequest;
+}
+//# sourceMappingURL=IotaNetwork.credentials.d.ts.map

package/dist/credentials/IotaNetwork.credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IotaNetwork.credentials.d.ts","sourceRoot":"","sources":["../../credentials/IotaNetwork.credentials.ts"],"names":[],"mappings":"AAOA,OAAO,EACN,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,YAAW,eAAe;IAClD,IAAI,SAAiB;IACrB,WAAW,SAAkB;IAC7B,gBAAgB,SAA4B;IAC5C,UAAU,EAAE,eAAe,EAAE,CAsH3B;IAGF,IAAI,EAAE,sBAAsB,CAM1B;CACF"}