Internode Communication Protocol

A unified protocol for nodes to discover, authenticate, and communicate - whether they’re blockchains, servers, or p2p peers.

Core Vision

Every Amigos node can connect to any other node, creating a mesh of interoperable services with built-in coordination channels.

Node Identity Types

1. Domain-Based Nodes

node1.amigos.dev
staging.mycompany.amigos.net
personal.alice.amigos.io

DNS-based discovery
TLS certificates for auth
RESTful or gRPC transport

2. Blockchain Nodes

cosmos-hub.amigos.ibc
ethereum.amigos.bridge
amigos-mainnet.chain

IBC for Cosmos chains
Bridge contracts for EVM
Native when same chain

3. P2P Identity Nodes

peer://Qm1234...
ipfs://bafybeig...
libp2p://12D3KooW...

Content-addressed identity
DHT discovery
Direct p2p connections

Connection Strategies

Blockchain → Blockchain

// Classic IBC with relayer
relayer := ibc.NewRelayer(chainA, chainB)
channel := relayer.CreateChannel()

// Future: Light client direct connection
client := chainB.LightClient()
channel := chainA.ConnectDirect(client)

Smart Node → Blockchain

// Direct connection with account
node := amigos.Node("mynode.amigos.dev")
account := node.Account() // Has keys
chain := amigos.Chain("cosmos-hub")
conn := chain.Connect(account) // No relayer needed

Node → Node (Non-blockchain)

// Authenticated connection
nodeA := amigos.Node("alice.amigos.dev")
nodeB := amigos.Node("bob.amigos.dev")

// Option 1: Direct auth
conn := nodeA.Connect(nodeB, auth.Token)

// Option 2: Via relay
relay := amigos.Relay("public-relay.amigos.dev")
conn := relay.Connect(nodeA, nodeB)

P2P Connections

// Peer identity based
peer := amigos.Peer("12D3KooW...")
conn := peer.Connect()

// Can upgrade to authenticated
conn.Authenticate(myIdentity)

The Transport Layer

Channel Types

type Channel interface {
    // Core transport
    Send(msg Message) error
    Receive() (Message, error)
    
    // Typed channels
    Transaction() TransactionChannel
    Query() QueryChannel
    Stream() StreamChannel
    Chat() ChatChannel
}

Message Types

Transactions - State changes
Queries - Read requests
Streams - Live data feeds
Chat - Coordination messages

The Chat System

Design Philosophy

Ephemeral by default - Not persisted unless requested
Multi-purpose - Human and machine communication
Structured - Can carry typed data
Subscribable - Live streaming support

Chat Channels

// System channels
conn.Chat().Subscribe("logs")      // All log messages
conn.Chat().Subscribe("events")    // State change events
conn.Chat().Subscribe("metrics")   // Performance data

// Custom channels
conn.Chat().Subscribe("team")      // Human coordination
conn.Chat().Subscribe("alerts")    // Important notifications
conn.Chat().Create("project-x")    // Create new channel

Log Streaming

// Subscribe to transaction logs
logStream := conn.Chat().Subscribe("logs")
for msg := range logStream {
    fmt.Printf("[%s] %s: %s\n", 
        msg.Timestamp,
        msg.Type,
        msg.Content)
}

// Example output:
// [2024-03-15 10:30:01] TX: Transfer 100 tokens from Alice to Bob
// [2024-03-15 10:30:02] STATE: Balance updated for 0x123...
// [2024-03-15 10:30:03] EVENT: NewBlock height=1234

Coordination Messages

// Human-readable coordination
chat := conn.Chat().Channel("coordination")

// Structured messages
chat.Send(Message{
    Type: "deployment",
    Data: map[string]interface{}{
        "version": "v1.2.3",
        "status": "starting",
        "nodes": []string{"node1", "node2"},
    },
})

// Plain text
chat.Send("Deployment complete, all systems normal")

Chat Features

Presence

// See who's connected
users := chat.Presence()
// ["alice@amigos.dev", "bot@monitoring", "relay@public"]

History

// Optional persistence
persistentChat := conn.Chat().Channel("important", 
    WithPersistence(7 * 24 * time.Hour))

// Replay recent messages
history := persistentChat.History(100) // Last 100 msgs

Filtering

// Subscribe with filters
logs := conn.Chat().Subscribe("logs",
    WithFilter("type", "transaction"),
    WithFilter("amount", ">1000"))

Protocol Stack

┌─────────────────────────┐
│     Application         │ ← Your service logic
├─────────────────────────┤
│     Chat System         │ ← Coordination layer
├─────────────────────────┤
│   Transaction/Query     │ ← Typed operations
├─────────────────────────┤
│    Channel Protocol     │ ← Multiplexing
├─────────────────────────┤
│     Transport           │ ← IBC/gRPC/WebSocket/P2P
└─────────────────────────┘

Use Cases

1. Multi-Chain Coordination

// Coordinate cross-chain transaction
mainnet := amigos.Connect("mainnet.amigos.chain")
sidechain := amigos.Connect("sidechain.amigos.chain")

coord := amigos.CoordinationChat(mainnet, sidechain)
coord.Send("Initiating cross-chain transfer")
// ... execute transfer
coord.Send("Transfer complete: tx1=0x123, tx2=0x456")

2. System Monitoring

// Central monitoring node
monitor := amigos.Node("monitor.amigos.dev")

nodes := []string{"node1", "node2", "node3"}
for _, node := range nodes {
    conn := monitor.Connect(node)
    go func(n string, c Connection) {
        logs := c.Chat().Subscribe("logs")
        for log := range logs {
            monitor.Process(n, log)
        }
    }(node, conn)
}

3. Deployment Coordination

// Orchestrate multi-node deployment
nodes := amigos.ConnectAll("prod-*.amigos.dev")
deploy := amigos.ChatRoom(nodes, "deployment")

deploy.Broadcast("Starting v2.0 deployment")
for _, node := range nodes {
    deploy.Send(node, "deploy:v2.0")
    // Wait for confirmation via chat
}
deploy.Broadcast("Deployment complete")

4. Debug Sessions

// Interactive debugging
dev := amigos.Connect("dev.alice.amigos.dev")
debug := dev.Chat().Interactive("debug")

debug.Send("watch state.users")
// Receives state changes for users

debug.Send("break Transfer")
// Pauses on Transfer transactions

debug.Send("inspect tx:0x123")
// Gets transaction details

Security Considerations

Authentication Levels

Public - Read-only access to public data
Authenticated - Verified identity
Authorized - Specific permissions
Admin - Full access

Channel Permissions

// Fine-grained permissions
chat.SetPermissions("team", 
    Read: ["authenticated"],
    Write: ["team-members"],
    Admin: ["alice", "bob"])

Encryption

Transport encryption (TLS/Noise)
Optional end-to-end encryption
Channel-specific keys

Implementation Roadmap

Phase 1: Basic Protocol

Node discovery
Simple authentication
Transaction forwarding
Basic chat

Phase 2: Advanced Features

IBC integration
P2P support
Persistent channels
Advanced filtering

Phase 3: Ecosystem

Relay networks
Chat bridges
Monitoring tools
SDK libraries

Benefits

For Developers

Unified communication model
Built-in debugging
Easy coordination
Live monitoring

For Operators

System visibility
Real-time alerts
Cross-node coordination
Audit trails

For Users

Transparent operations
Better debugging
Community interaction
System understanding

The Philosophy

Traditional blockchain nodes are isolated islands. Amigos nodes are social - they discover, connect, and communicate naturally.

The chat system isn’t an add-on - it’s fundamental to how nodes coordinate, debug, and evolve together. Every operation can be observed, every action can be coordinated.

By making nodes conversational, we make distributed systems understandable.

internode-protocol