n8n-nodes-secret

[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 for Secret Network - the blockchain with privacy-preserving smart contracts. This package enables seamless integration of Secret Network operations into your n8n workflows, including encrypted smart contracts, private token operations, staking, IBC transfers, and DeFi integrations.

Features

• 🔒 Privacy-First: Full support for Secret Network's encrypted smart contracts with viewing keys and permits
• 💰 SNIP-20 Tokens: Complete private fungible token operations including transfers, allowances, and history
• 🖼️ SNIP-721 NFTs: Private NFT operations, metadata queries, and ownership management
• 🏦 Staking: Delegate, undelegate, redelegate, and claim rewards from validators
• 🌉 IBC Transfers: Cross-chain transfers to Cosmos ecosystem chains via IBC protocol
• 🔗 Bridge Operations: ETH/BSC bridge integrations for wrapped assets
• 📊 Shade Protocol: DeFi operations including ShadeSwap, SILK stablecoin, and SHD governance
• 🔐 Viewing Keys & Permits: Secure private data access with multiple authentication methods
• ⚡ Real-time Triggers: Event-based workflow automation for blocks, transactions, and token transfers
• 🛡️ Security: Code hash validation, encrypted inputs, and TEE protection

Installation

Community Nodes (Recommended)

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

Manual Installation

# Navigate to your n8n custom nodes directory
cd ~/.n8n/custom

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

# Install dependencies and build
npm install
npm run build

# Restart n8n
n8n start

Development Installation

# Extract the package
unzip n8n-nodes-secret.zip
cd n8n-nodes-secret

# 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-secret

# Restart n8n
n8n start

Docker Installation

Add to your docker-compose.yml volumes:

volumes:
  - ~/.n8n:/home/node/.n8n
  - /path/to/n8n-nodes-secret:/home/node/.n8n/custom/n8n-nodes-secret

Credentials Setup

Secret Network Credentials

Main credential for interacting with Secret Network.

| Field | Description | Required | |-------|-------------|----------| | Network | Select mainnet, testnet, local, or custom | Yes | | Mnemonic Phrase | 24-word wallet mnemonic (BIP39) | Yes | | HD Path | Derivation path (default: m/44'/529'/0'/0/0) | No | | LCD Endpoint | Custom LCD/REST API endpoint | For custom | | RPC Endpoint | Custom RPC endpoint | No | | Chain ID | Custom chain ID | For custom |

Viewing Key Credentials

For accessing private contract data.

| Field | Description | Required | |-------|-------------|----------| | Contract Address | SNIP-20/721 contract address | Yes | | Viewing Key | Your viewing key for the contract | Yes |

Secret API Credentials

For external API integrations.

| Field | Description | Required | |-------|-------------|----------| | API Endpoint | API base URL | Yes | | API Key | Authentication key | If required |

Resources & Operations

Account (7 operations)

• Get SCRT Balance: Query native SCRT balance for any address
• Get All Balances: Query all token balances including IBC tokens
• Get Account Info: Retrieve account details including sequence number
• Transfer SCRT: Send native SCRT to another address
• Validate Address: Check if an address is valid Secret Network format
• Get Delegations: List all staking delegations for an address
• Get Rewards: Query pending staking rewards

Transaction (4 operations)

• Get Transaction: Retrieve transaction details by hash
• Get Status: Check transaction confirmation status
• Simulate: Simulate transaction execution without broadcasting
• Estimate Gas: Calculate gas requirements for a transaction

Contract (6 operations)

• Get Contract Info: Query contract metadata and code info
• Get Code Hash: Retrieve contract code hash for verification
• Query (Public): Execute public contract queries
• Query (Viewing Key): Query private data with viewing key
• Execute Contract: Execute contract messages with state changes
• Get Contracts by Code ID: List all instances of a contract code

Privacy (5 operations)

• Create Viewing Key: Generate a new viewing key for a contract
• Set Viewing Key: Register a viewing key with a contract
• Create Permit: Generate a signed permit for authentication
• Revoke Permit: Revoke an existing permit
• Query with Permit: Execute queries using permit authentication

SNIP-20 Token (9 operations)

• Get Token Info: Query token metadata (name, symbol, decimals)
• Get Balance: Query private token balance with viewing key
• Transfer: Transfer tokens to another address
• Send: Transfer with callback to recipient contract
• Get Transfer History: Query historical transfers
• Set Viewing Key: Create/update viewing key for token
• Increase Allowance: Approve spending by another address
• Decrease Allowance: Reduce approved spending amount
• Get Allowance: Check current allowance for spender

SNIP-721 NFT (7 operations)

• Get NFT Info: Query NFT metadata and attributes
• Get NFTs by Owner: List all NFTs owned by an address
• Transfer NFT: Transfer NFT ownership
• Send NFT: Transfer with callback to recipient contract
• Set Viewing Key: Create viewing key for NFT contract
• Approve: Approve operator for NFT management
• Revoke: Revoke operator approval

Staking (9 operations)

• Get Validators: List all active validators
• Get Validator Info: Query specific validator details
• Delegate: Stake SCRT with a validator
• Undelegate: Begin unbonding delegation (21-day period)
• Redelegate: Move delegation between validators
• Get Delegations: List your active delegations
• Get Unbonding: List pending unbonding delegations
• Get Staking Rewards: Query accumulated rewards
• Claim Rewards: Withdraw staking rewards

IBC (4 operations)

• IBC Transfer: Cross-chain transfer via IBC protocol
• Get Channels: List available IBC channels
• Get Channel Info: Query specific channel details
• Get Denom Trace: Trace IBC token origin

Block (4 operations)

• Get Latest Block: Query most recent block
• Get Block by Height: Query specific block by height
• Get Chain ID: Get current network chain ID
• Get Network Status: Check network health and sync status

Utility (4 operations)

• uscrt to SCRT: Convert micro-units to SCRT (÷1,000,000)
• SCRT to uscrt: Convert SCRT to micro-units (×1,000,000)
• Validate Address: Verify address format
• Get Network Info: Get current connection details

Trigger Node

The Secret Network Trigger node enables event-based workflow automation:

| Trigger Type | Description | |--------------|-------------| | New Block | Fires on each new block | | SCRT Received | Fires when SCRT is received at watched address | | SCRT Sent | Fires when SCRT is sent from watched address | | Contract Executed | Fires when a specific contract is executed | | Token Transfer (SNIP-20) | Fires on private token transfers (requires viewing key) | | NFT Transfer (SNIP-721) | Fires on NFT transfers (requires viewing key) | | Delegation Changed | Fires when delegation status changes | | Rewards Available | Fires when rewards exceed threshold | | IBC Transfer Received | Fires on incoming IBC transfers | | Transaction Confirmed | Fires when specific transaction is confirmed |

Usage Examples

Get SCRT Balance

// Resource: Account
// Operation: Get SCRT Balance
{
  "address": "secret1abc...xyz"
}
// Returns: { "balance": "1000000", "denom": "uscrt", "formatted": "1.0 SCRT" }

Transfer SCRT

// Resource: Account
// Operation: Transfer SCRT
{
  "recipient": "secret1recipient...",
  "amount": "1.5",
  "memo": "Payment for services"
}

Query SNIP-20 Token Balance

// Resource: SNIP-20 Token
// Operation: Get Balance
{
  "contractAddress": "secret1token...",
  "viewingKey": "api_key_..."
}
// Returns: { "balance": "1000000000" }

Create Viewing Key

// Resource: Privacy
// Operation: Create Viewing Key
{
  "contractAddress": "secret1contract...",
  "entropy": "random_string_for_key_generation"
}
// Returns: { "viewing_key": "api_key_..." }

Delegate SCRT

// Resource: Staking
// Operation: Delegate
{
  "validatorAddress": "secretvaloper1...",
  "amount": "100"
}

IBC Transfer to Osmosis

// Resource: IBC
// Operation: IBC Transfer
{
  "sourceChannel": "channel-1",
  "receiver": "osmo1recipient...",
  "amount": "10",
  "denom": "uscrt"
}

Monitor Token Transfers (Trigger)

// Node: Secret Network Trigger
// Trigger On: Token Transfer (SNIP-20)
{
  "contractAddress": "secret1token...",
  "viewingKey": "your_viewing_key",
  "watchAddress": "secret1youraddress..."
}

Secret Network Concepts

Viewing Keys

Viewing keys are user-generated passwords that allow querying private contract data. Each user creates their own viewing key for each contract they interact with.

// Creating a viewing key
const result = await contract.execute({
  create_viewing_key: { entropy: "random_string" }
});
// Result: { viewing_key: "api_key_..." }

Permits

Permits are signed messages that provide temporary authentication without storing keys on-chain. They can have expiration times and limited permissions.

// Permit structure
{
  "params": {
    "permit_name": "my_permit",
    "allowed_tokens": ["secret1token..."],
    "chain_id": "secret-4",
    "permissions": ["balance", "history"]
  },
  "signature": "..."
}

Code Hash Validation

Every Secret Network contract has a code hash that must be verified to prevent interacting with malicious contracts:

// Always verify code hash before interaction
const expectedHash = "abc123...";
const actualHash = await client.query.compute.codeHashByContractAddress(address);
if (actualHash !== expectedHash) {
  throw new Error("Code hash mismatch - possible malicious contract");
}

Networks

| Network | Chain ID | LCD Endpoint | |---------|----------|--------------| | Mainnet | secret-4 | https://lcd.secret.express | | Testnet | pulsar-3 | https://api.pulsar.scrttestnet.com | | Local | secretdev-1 | http://localhost:1317 |

Error Handling

The node includes comprehensive error handling:

| Error | Cause | Solution | |-------|-------|----------| | Invalid viewing key | Wrong or expired key | Create new viewing key | | Out of gas | Insufficient gas limit | Increase gas in options | | Account sequence mismatch | Rapid transactions | Wait and retry | | Code hash mismatch | Contract verification failed | Verify contract address | | Network error | Connection issues | Check endpoint accessibility |

Security Best Practices

1. Never share mnemonics: Store securely in n8n credentials
2. Rotate viewing keys: Periodically create new viewing keys
3. Use permits wisely: Set appropriate expiration times
4. Validate code hashes: Always verify before contract interaction
5. Test on testnet: Use pulsar-3 before mainnet operations
6. Secure credentials: Use n8n's built-in credential encryption
7. Monitor transactions: Set up alerts for unexpected activity

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in watch mode
npm run dev

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA
• Email: [email protected]

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

1. Code follows the existing style (run npm run lint)
2. All tests pass (npm test)
3. New features include tests
4. Documentation is updated
5. Commits follow conventional commit format

Support

• Documentation: Secret Network Docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• n8n Community: n8n Community Forum

Acknowledgments

• Secret Network - The privacy-first blockchain
• SecretJS - Official JavaScript SDK
• n8n - Workflow automation platform
• Shade Protocol - DeFi on Secret Network