Messenger Node CLI Skill

When the user asks to perform any messenger operation, use your command execution tool to run the appropriate script. All scripts live in the messenger project directory.

Setup & Dependencies

The ws dependency is required. Run npm install if needed.

Network Activity

At runtime, scripts fetch a supernode list from the FLO blockchain and establish wss/https connections to discovered supernodes. Network activity is expected and required for the messenger to function.

Security & Credentials

• All scripts strictly require the FLO_PRIVATE_KEY environment variable (except contacts_node.js and pubkey_node.js --action my-pubkey).
• NEVER ask or allow the user to paste their private key in the chat. If the key is missing, instruct them to set it securely via system environment variables.

Runtime Transparency

All bundled libraries loaded at runtime via vm.runInThisContext are static, local files — no remote code is fetched or executed:

Messaging scripts (send_node.js, receive_node.js, mail_node.js, groups_node.js, pubkey_node.js, multisig_node.js) load via node_shared.js:

flo_node.js (blockchain transactions) loads only 3 of the above — floCloudAPI.js is NOT loaded as no supernode messaging is needed for direct blockchain transactions.

contacts_node.js loads no FLO libraries at all — pure local JSON file operations.

New standard-operations Node scripts (added alongside existing scripts):

scripts/floDapps.js is a browser startup framework (IndexedDB init, login, cloud boot). It has no meaningful Node.js equivalent — its individual sub-operations are covered by the existing messenger scripts and idb_node.js.

scripts/blockchainAddresses.js is NOT loaded by any Node script. It is a browser-only utility used by the web app (index.html) to display multi-chain addresses in the UI. No agent-facing script references, requires, or executes it. The private key is used solely for FLO messaging and transaction signing.

Local files written by this skill:

• contacts.json — contact address book (contacts_node.js only)
• groups_cache.json — group membership cache (groups_node.js only)
• multisig_cache.json — pending multisig pipeline state (multisig_node.js only)

Blockchain Activity & Fees

• Sending messages writes data to the live FLO blockchain requiring a microscopic dust fee (0.0002 FLO per send) — this is a standard blockchain protocol requirement.

Execution Instructions (Strict Adherence Required)

1. Use your command execution tool — DO NOT just print the command as text.
2. Wait for user approval before executing.
3. Use the exact formats shown below.

Script Reference

Sending Messages — send_node.js

node send_node.js --receiver "<RECEIVER_FLO_ID>" --message "<MESSAGE>"

Optional: Append --encrypt "<RECEIVER_PUBLIC_KEY>" to encrypt the message.

Receiving Messages — receive_node.js

node receive_node.js

Flags:

• --limit <N> — Limit to N most recent messages (default: 50)
• --sender <FLO_ID> — Filter by sender address
• --decrypt — Auto-decrypt encrypted payloads
• --watch — Watch mode: live stream of incoming messages (long-running)

Contacts — contacts_node.js

No FLO_PRIVATE_KEY needed. Contacts stored locally in contacts.json.

# List all contacts
node contacts_node.js --action list

# Add or update a contact
node contacts_node.js --action add --address "<FLO_ID>" --name "<NAME>"

# Remove a contact
node contacts_node.js --action remove --address "<FLO_ID>"

# Look up a contact by address
node contacts_node.js --action lookup --address "<FLO_ID>"

Public Keys — pubkey_node.js

# Show your own FLO ID and public key (no cloud needed)
node pubkey_node.js --action my-pubkey

# Look up the public key of any FLO address from the cloud
node pubkey_node.js --action get --address "<FLO_ID>"

# Send a public key request to another user
node pubkey_node.js --action request --address "<FLO_ID>" --message "<OPTIONAL_NOTE>"

Mail — mail_node.js

Long-form messages with subject and body. Supports multiple recipients.

# Send a mail (multiple --to flags or comma-separated addresses allowed)
node mail_node.js --action send --to "<FLO_ID1>,<FLO_ID2>" --subject "<SUBJECT>" --body "<BODY>"

# List received mails
node mail_node.js --action list --limit 20

# Read the full content of a specific mail
node mail_node.js --action read --ref "<MAIL_REF>"

Groups — groups_node.js

Requires groups_cache.json to be populated first via --action fetch.

# Pull group memberships from cloud and cache locally (run this first!)
node groups_node.js --action fetch

# List all cached groups
node groups_node.js --action list

# Send an encrypted message to a group
node groups_node.js --action send --group "<GROUP_ID>" --message "<MESSAGE>"

# Read group messages (decrypted)
node groups_node.js --action read --group "<GROUP_ID>" --limit 30

Note: Group IDs are long FLO addresses — use --action list to find them after fetching.

FLO Transactions — flo_node.js

Send FLO tokens, check balances, and view transaction history directly on-chain.

Warning: send broadcasts a real on-chain transaction. Funds move immediately and cannot be reversed. The --memo text is stored publicly on the FLO blockchain.

# Check your own FLO balance
node flo_node.js --action balance

# Check balance of any FLO address
node flo_node.js --action balance --address "<FLO_ID>"

# Send FLO tokens (with optional on-chain memo)
node flo_node.js --action send --to "<FLO_ID>" --amount <FLO> --memo "<TEXT>"

# View transaction history (your address)
node flo_node.js --action history --limit 20

# View transaction history for any address
node flo_node.js --action history --address "<FLO_ID>" --limit 20

# Write custom data to the blockchain
node flo_node.js --action write-data --data "<TEXT>" --to "<FLO_ID>"

# Read raw data transactions for an address
node flo_node.js --action read-data --address "<FLO_ID>"

# Send FLO to multiple receivers in a single transaction
node flo_node.js --action send-tx-multiple --privkeys "<WIF1>,<WIF2>" --receivers "<FLO_ID1>:0.1,<FLO_ID2>:0.5"

# Merge UTXOs to consolidate dust
node flo_node.js --action merge-utxos

🔒 Cryptography — crypto_node.js

Pure cryptographic operations. Offline, no network required.

# Generate random data
node crypto_node.js --action rand-string --length 16
node crypto_node.js --action rand-int --min 1 --max 100

# Address validation
node crypto_node.js --action validate-address --address "<FLO_ID>"
node crypto_node.js --action verify-pubkey --pubkey "<HEX>"

# Identity retrieval
node crypto_node.js --action get-pubkey --privkey "<WIF>"
node crypto_node.js --action get-address --pubkey "<HEX>"

# Encrypt / Decrypt
node crypto_node.js --action encrypt --data "<TEXT>" --pubkey "<HEX>"
node crypto_node.js --action decrypt --data "<HEX>" --privkey "<WIF>"

# Sign / Verify
node crypto_node.js --action sign --data "<TEXT>" --privkey "<WIF>"
node crypto_node.js --action verify-sign --data "<TEXT>" --sig "<HEX>" --pubkey "<HEX>"

# Shamir's Secret Sharing
node crypto_node.js --action shamir-create --secret "<TEXT>" --shares <N> --threshold <M>
node crypto_node.js --action shamir-retrieve --shares "S1,S2,S3"
node crypto_node.js --action shamir-verify --shares "S1,S2" --secret "<TEXT>"

☁️ Supernode Cloud API — cloud_node.js

Raw interaction with the FLO Supernode Cloud infrastructure.

node cloud_node.js --action send-general --data "<TEXT>" --type "<TYPE>"
node cloud_node.js --action request-general --type "<TYPE>"
node cloud_node.js --action request-object --object "<NAME>"

🛠️ DApp Tools — dapp_node.js

Node equivalents for administrative floDapps operations.

# Add/Remove SubAdmins on the blockchain
node dapp_node.js --action manage-subadmins --add "FLO_ID1" --rm "FLO_ID2"

# Encrypt your private key with a PIN via Shamir shares
node dapp_node.js --action secure-privkey --pin "<PASSWORD>"

# Get next general data
node dapp_node.js --action get-next-general --type "<TYPE>" [--vector "<CLOCK>"]

FLO Multisig — multisig_node.js

FLO multisig address generation, collaborative transaction signing, and pending transaction management.

Note: Multisig transactions require M-of-N co-signers. The create-tx action partially signs the transaction and distributes it to co-signers via an encrypted cloud pipeline. Co-signers then run sign-tx to add their signature. Once M signatures are collected, the transaction is automatically broadcast.

Warning: create-tx sends real FLO funds when eventually broadcast. Memos are stored publicly on-chain.

# Step 1: Generate a multisig address (no FLO_PRIVATE_KEY needed)
node multisig_node.js --action generate-address --pubkeys "PUB1,PUB2,PUB3" --required 2

# Step 2: Create and sign a multisig tx (initiator)
# Supports single receiver/amount or multiple (comma-separated or multiple --to/--amount flags matching in length)
node multisig_node.js --action create-tx \
  --address "<MULTISIG_FLO_ID>" \
  --redeem-script "<REDEEM_SCRIPT_HEX>" \
  --to "<RECEIVER_FLO_ID1>,<RECEIVER_FLO_ID2>" \
  --amount "1.5,0.5" \
  --memo "payments"

# Step 3 (co-signer): Sign the pending tx
node multisig_node.js --action sign-tx --pipeline "<PIPELINE_ID>"

# View status of a pending tx
node multisig_node.js --action view-tx --pipeline "<PIPELINE_ID>"

# List all locally cached pending multisig transactions
node multisig_node.js --action list-pending

# Manually broadcast a fully-signed tx
node multisig_node.js --action broadcast --pipeline "<PIPELINE_ID>"

FLO Token Operations — token_node.js

Query and transfer FLO tokens (fungible tokens on the FLO blockchain).

Warning: send broadcasts a real on-chain token transfer. Tokens move immediately and cannot be reversed.

# Check your own token balance (default token: rupee)
node token_node.js --action balance

# Check balance for any address / any token
node token_node.js --action balance --address "<FLO_ID>" --token rupee

# Send tokens
node token_node.js --action send --to "<FLO_ID>" --amount <N> --token rupee --message "<NOTE>"

# Token transaction history
node token_node.js --action history
node token_node.js --action history --address "<FLO_ID>" --token rupee

# Details of a specific token transaction
node token_node.js --action tx --txid "<TXID>"

# Bulk transfer to multiple receivers
node token_node.js --action bulk-transfer --receivers "<FLO_ID1>:10,<FLO_ID2>:20"

# Parse token tx data
node token_node.js --action parse-tx --txdata "<JSON>"

# Raw fetch against token API
node token_node.js --action raw-fetch --apicall "api/v1.0/getTx?txid=..."

Flags:

• --address <FLO_ID> — Target address (defaults to your address derived from FLO_PRIVATE_KEY)
• --token <TOKEN> — Token name (default: rupee)
• --message <TEXT> — Optional note attached to the token transfer

Bitcoin Operations — btc_node.js

Bitcoin blockchain queries and address tools. Uses multiple APIs with automatic failover (Blockcypher, Blockstream, Mempool.space, Blockchain.info).

Note: No FLO_PRIVATE_KEY required. All read actions are public. broadcast sends a pre-signed raw transaction you provide.

# BTC balance for any address
node btc_node.js --action balance --address "<BTC_ADDR>"

# Transaction history
node btc_node.js --action history --address "<BTC_ADDR>"

# Transaction details
node btc_node.js --action tx --txid "<TXID>"

# Generate a new BTC key pair (legacy + segwit + bech32 addresses)
node btc_node.js --action new-keys

# Validate a BTC address and show its type (legacy/bech32/segwit/multisig)
node btc_node.js --action validate --address "<BTC_ADDR>"

# Generate a multisig address
node btc_node.js --action multisig --pubkeys "PUB1,PUB2,PUB3" --required 2
node btc_node.js --action multisig --pubkeys "PUB1,PUB2" --required 2 --no-bech32

# Decode a redeem script
node btc_node.js --action decode-script --hex "<REDEEM_SCRIPT_HEX>"

# Convert an address between formats
node btc_node.js --action convert --address "<ADDR>" --from legacy --to bech32
node btc_node.js --action convert --address "<ADDR>" --from bech32 --to legacy

# Broadcast a pre-signed raw transaction
node btc_node.js --action broadcast --hex "<SIGNED_RAW_TX_HEX>"

Address type options for --from/--to: legacy, bech32, segwit, multisig

Local Key-Value Storage — idb_node.js

File-backed key-value store that mirrors the browser compactIDB API. Data is persisted to ./idb_data/<db>.json.

Note: No FLO_PRIVATE_KEY required. No network activity. Pure local file operations.

# List all local databases
node idb_node.js --action dbs

# List stores in a database
node idb_node.js --action stores --db "<DB_NAME>"

# Initialise a database with stores
node idb_node.js --action init --db "<DB_NAME>" --stores "contacts,settings,messages"

# List all records in a store
node idb_node.js --action list --db "<DB_NAME>" --store "<STORE>"

# Read a single record
node idb_node.js --action read --db "<DB_NAME>" --store "<STORE>" --key "<KEY>"

# Add a new record (fails if key already exists)
node idb_node.js --action add --db "<DB_NAME>" --store "<STORE>" --key "<KEY>" --value '"Alice"'

# Write (upsert) a record (value is JSON or plain string)
node idb_node.js --action write --db "<DB_NAME>" --store "<STORE>" --key "<KEY>" --value '"Alice"'
node idb_node.js --action write --db "<DB_NAME>" --store "<STORE>" --key "cfg" --value '{"theme":"dark"}'

# Remove a record
node idb_node.js --action remove --db "<DB_NAME>" --store "<STORE>" --key "<KEY>"

# Clear all records in a store
node idb_node.js --action clear --db "<DB_NAME>" --store "<STORE>"

# Delete an entire database
node idb_node.js --action delete-db --db "<DB_NAME>"

Standard Operations Library Reference (Browser)

The following libraries are browser/DApp-side. They are documented here so the agent understands their API when working with FLO DApp code or the web app (index.html).

📦 compactIDB — scripts/compactIDB.js

Compact browser IndexedDB wrapper. Exposes window.compactIDB.

All methods return Promises.

🚀 floDapps — scripts/floDapps.js

FLO DApp framework for browser apps. Handles startup, credentials, app config, and user data. Exposes window.floDapps.

Startup & Lifecycle

Startup Options

User Object (floDapps.user)

Data & Messaging

App Config (admin only)

Credential Management

Global shortcuts set on window: myFloID, myUserID, myPubKey, myPrivKey

🪙 floTokenAPI — scripts/floTokenAPI.js

FLO token (fungible token) operations. Exposes window.floTokenAPI.

Properties:

• floTokenAPI.currency — Current default token name (get/set)
• floTokenAPI.URL — Current API base URL

Warning: sendToken and bulkTransferTokens broadcast real on-chain token transfers. Token amounts are checked against balance before sending.

₿ btcOperator — scripts/btcOperator.js

Bitcoin blockchain operations — address generation, balance, transactions, multi-sig. Exposes window.btcOperator.

Address & Key Utilities

Multisig

Address Conversion

Blockchain Queries

Utilities

Supported API Providers (automatic failover): Blockcypher, Blockstream, Mempool.space, Blockchain.info, Coinb.in

Quick Reference Table