A blockchain-based security framework for AI agent communication — providing end-to-end encrypted, authenticated channels between AI agents using decentralized identity (DID), HPKE key agreement (RFC 9180), and HTTP Message Signatures (RFC 9421).
For release history and recent changes, see CHANGELOG.md.
- Key Features
- Quick Start
- Architecture
- Usage
- Testing
- Supported Networks
- Live Deployments
- Multi-Language Bindings
- Documentation
- Contributing
- License
- Support & Acknowledgments
- End-to-End Encrypted Handshake — HPKE (RFC 9180) with X25519 key agreement
- RFC 9421 HTTP Message Signatures — Verifiable agent-to-agent communication
- Multi-Chain DID — Ethereum, Kaia, and Solana network integration
- AgentCardRegistry — Three-phase commit-reveal registration with ERC-8004 compliance
- Multi-Key Support — Ed25519, Secp256k1, and X25519 cryptographic operations
- Session Management — Automatic key rotation, nonce tracking, and replay protection
- A2A Protocol Integration — Native support for Google Agent-to-Agent protocol
- Protocol-Agnostic Transport — HTTP, WebSocket, and pluggable architecture
- Zero External Dependencies — Self-contained core for better maintainability
- Go 1.25.2+ (see docs/GO_VERSION_REQUIREMENT.md)
- Node.js 22+ and npm (for smart contract development)
- Git
# Clone
git clone https://github.com/SAGE-X-project/sage.git
cd sage
# Go dependencies
go mod download
# Smart contract dependencies
cd contracts/ethereum && npm install && cd ../..
# Build all CLI tools
make build
# Compile smart contracts
cd contracts/ethereum && npm run compile# Go tests
make test
# Smart contract tests (202 passing)
cd contracts/ethereum && npm test
# Integration tests
make test-integrationSee docs/BUILD.md for cross-platform compilation, library builds, and language integration details.
sage/
├── core/ # Core RFC 9421 implementation
│ ├── rfc9421/ # HTTP message signatures (canonicalization, signing, verification)
│ └── message/ # Message processing, validation, ordering, and deduplication
├── crypto/ # Cryptographic operations
│ ├── keys/ # Ed25519, Secp256k1, X25519 key pair implementations
│ ├── chain/ # Blockchain-specific providers (Ethereum, Solana)
│ ├── storage/ # Secure key storage (file, memory)
│ ├── vault/ # Hardware-backed secure storage with OS keychain integration
│ └── formats/ # JWK, PEM key format converters
├── did/ # Decentralized Identity
│ ├── ethereum/ # Ethereum DID client with enhanced provider
│ ├── solana/ # Solana DID client
│ ├── manager.go # Multi-chain DID management
│ └── resolver.go # DID document resolution with caching
├── handshake/ # Secure session establishment
│ ├── client.go # Handshake initiator implementation
│ ├── server.go # Handshake responder with peer caching
│ └── types.go # Invitation, Request, Response, Complete messages
├── hpke/ # HPKE (RFC 9180) implementation
│ ├── client.go # HPKE sender (encapsulation)
│ ├── server.go # HPKE receiver (decapsulation)
│ └── common.go # Shared HPKE utilities
├── session/ # Session and key management
│ ├── manager.go # Session lifecycle, cleanup, and key ID binding
│ ├── session.go # Secure session with ChaCha20-Poly1305 AEAD
│ ├── nonce.go # Replay attack prevention with nonce cache
│ └── metadata.go # Session state and expiration tracking
├── transport/ # Protocol-agnostic transport layer
│ ├── interface.go # MessageTransport interface
│ ├── mock.go # MockTransport for testing
│ ├── selector.go # Runtime transport selection
│ ├── http/ # HTTP/REST transport implementation
│ ├── websocket/ # WebSocket transport implementation
│ └── a2a/ # A2A adapter for backward compatibility
├── health/ # Health monitoring system
│ ├── checker.go # Component health checks
│ └── server.go # HTTP health endpoint
├── config/ # Configuration management
│ ├── config.go # Unified configuration loader
│ ├── blockchain.go # Blockchain-specific settings
│ └── validator.go # Configuration validation
├── contracts/ # Smart contracts
│ └── ethereum/ # Ethereum contracts, tests, deployment scripts
├── cmd/ # CLI applications
│ ├── sage-crypto/ # Cryptographic operations CLI
│ ├── sage-did/ # DID management CLI
│ └── deployment-verify/ # Blockchain deployment verification CLI
├── examples/ # Usage examples
│ └── mcp-integration/ # Model Context Protocol integration examples
├── tests/ # Testing infrastructure
│ ├── integration/ # End-to-end integration tests
│ ├── random/ # Randomized fuzzing tests
│ └── handshake/ # Handshake integration tests
├── docs/ # Documentation
│ ├── handshake/ # Handshake protocol documentation (EN/KO)
│ ├── dev/ # Developer guides and security design
│ └── assets/ # Architecture diagrams
├── scripts/ # Test and deployment scripts
└── internal/ # Internal utilities and helpers
SAGE uses a server static X25519 KEM, a client ephemeral KEM (enc), plus Ed25519 signatures, an ackTag (key-confirmation), and optional cookies for DoS control.
-
Initialize (Client → Server)
- Sends: enc (HPKE encapsulation), ephC (client X25519 for PFS), info / exportCtx, nonce / ts, DID signature, and (optional) cookie.
- Server: verify cookie early → verify DID signature → check replay/clock-skew/context → HPKE Open → generate ephS → compute ssE2E → derive seed → create session.
-
Acknowledge (Server → Client)
- Sends: kid, ackTagB64 (key confirmation), ephS, and a signed server envelope.
- Client: verify ackTag → verify server signature → bind kid ↔ session → derive c2s/s2c AEAD keys and start the channel.
See docs/handshake/hpke-based-handshake-en.md for the full protocol specification.
# Generate Ed25519 key pair (for DID signatures)
./build/bin/sage-crypto generate -t ed25519 -o keys/agent.key
# Generate Secp256k1 key pair (for Ethereum)
./build/bin/sage-crypto generate -t secp256k1 -o keys/ethereum.key
# Generate X25519 key pair (for HPKE encryption)
./build/bin/sage-crypto generate -t x25519 -o keys/hpke.key
# List all keys
./build/bin/sage-crypto list -d keys/# Phase 1: Commit with stake
./build/bin/sage-did commit \
--chain ethereum \
--key keys/ethereum.key \
--name "My AI Agent" \
--endpoint "https://api.myagent.com"
# Phase 2: Register (after 1–60 min)
./build/bin/sage-did register \
--chain ethereum \
--key keys/ethereum.key
# Phase 3: Activate (after 1+ hour)
./build/bin/sage-did activate \
--chain ethereum \
--key keys/ethereum.key
# Resolve a DID
./build/bin/sage-did resolve did:sage:ethereum:0x...import (
"github.com/sage-x-project/sage/pkg/agent/hpke"
"github.com/sage-x-project/sage/pkg/agent/session"
"github.com/sage-x-project/sage/pkg/agent/did"
)
// Client side (Agent A)
client := hpke.NewClient(transport, resolver, myKeyPair, string(myDID), infoBuilder, sessionManager)
// Initialize session
ctxID := "ctx-" + uuid.NewString()
kid, _ := client.Initialize(ctx, ctxID, clientDID, serverDID)
// Get session and encrypt/decrypt
sess, _ := sessionManager.GetByKeyID(kid)
cipher, _ := sess.Encrypt(body)
plain, _ := sess.Decrypt(cipher)import "github.com/sage-x-project/sage/pkg/agent/core/rfc9421"
// Build and sign HTTP message
builder := rfc9421.NewMessageBuilder()
msg := builder.
Method("POST").
Authority("api.example.com").
Path("/api/v1/chat").
Header("Content-Type", "application/json").
Body([]byte(cipherRequestBody)).
Build()
verifier := rfc9421.NewHTTPVerifier(sess, sessionManager)
signature, _ := verifier.SignRequest(msg, sigName, []string{
"@method", "@authority", "@path", "content-type", "content-digest",
}, privKey)import "github.com/sage-x-project/sage/pkg/agent/did"
// Generate a key pair and derive Ethereum address
keyPair, _ := crypto.GenerateSecp256k1KeyPair()
ownerAddr, _ := did.DeriveEthereumAddress(keyPair)
// Create DID with owner address
agentDID := did.GenerateAgentDIDWithAddress(did.ChainEthereum, ownerAddr)
// Export as A2A-compliant agent card
card := did.GenerateA2ACard(agentDID, metadata)For detailed A2A integration, see SAGE A2A Integration Guide and sage-a2a-go.
SAGE supports YAML configuration files and environment variables:
blockchain:
ethereum:
rpc_url: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
contract_address: "0x..."
chain_id: 1
crypto:
key_dir: "./keys"
default_algorithm: "ed25519"
session:
max_age: "1h"
idle_timeout: "10m"
cleanup_interval: "30s"See environment variable options and Hardhat setup details in the full configuration docs.
make test # All tests
make test-quick # Exclude slow integration tests
make test-integration # Integration tests (starts Hardhat node)
make bench # Benchmark tests
make random-test # Random fuzzing tests
go test -race ./... # Race detection
go test -cover ./... # Coveragecd contracts/ethereum
npm test # All 202 contract tests
npm run coverage # Coverage report
npm run test:integration # Integration tests./tools/scripts/verify_all_features.sh # 85+ feature tests
./tools/scripts/quick_verify.sh # Quick 5-check verification- Ethereum — Full support with ENS integration
- Kaia (Cypress) — Production deployment
- BSC, Base, Arbitrum, Optimism — EVM-compatible deployment ready
- Solana — In development
- Sepolia (Ethereum), Kairos (Kaia), BSC Testnet, Base Sepolia, Arbitrum Sepolia, Optimism Sepolia, Solana Devnet
| Contract | Address |
|---|---|
| AgentCardRegistry | 0xC7eCF7Ad6ee71CB0d94f0eb00F46f1DDf432a808 |
| AgentCardVerifyHook | 0xf3be150cd4EC0819bef95890DeeE0B71d9C94F6b |
| ERC8004IdentityRegistry | 0x5B0763c3649eee889966dF478a73e53Df0420C84 |
| ERC8004ReputationRegistry | 0xE953B278fd2378BA4987FE07f71575dd3353C9a8 |
| ERC8004ValidationRegistry | 0x97291e2D3023d166878ed45BBD176F92E5Fda098 |
See contracts/ethereum/README.md for deployment details and verification status.
| Contract | Address |
|---|---|
| SageRegistryV2 | 0x487d45a678eb947bbF9d8f38a67721b13a0209BF |
| ERC8004ValidationRegistry | 0x4D31A11DdE882D2B2cdFB9cCf534FaA55A519440 |
| ERC8004IdentityRegistry | 0x02439d8DA11517603d0DE1424B33139A90969517 |
Note: Legacy contracts are deprecated. Use AgentCardRegistry for new deployments.
SAGE provides bindings for multiple programming languages:
| Language | Type | Details |
|---|---|---|
| Go | Native | Primary implementation |
| C/C++ | Static/shared library | .a, .so/.dylib/.dll |
| Python | Web3.py + ctypes | Smart contract + library bindings |
| Rust | FFI | Via static library |
| JavaScript/TypeScript | Ethers.js | Smart contract bindings |
See docs/BUILD.md for library build instructions and integration examples.
- Documentation Index — Complete documentation catalog
- Architecture Guide — System architecture and design patterns
- Build Instructions — Compilation, cross-platform, and library builds
- API Reference — HTTP and gRPC API documentation
- Handshake Protocol — HPKE handshake specification
- Security Design — Security architecture
- KEM Key Integration — X25519 KEM key support
- Contracts README — AgentCard contracts, deployment, testing
- AgentCard Migration Guide — Migrating from legacy registries
- Contributing Guide — How to contribute
- Testing Guide — Testing strategies and best practices
- CI/CD Pipeline — Continuous integration workflows
- Coding Guidelines — Code quality standards
We welcome contributions! Please see CONTRIBUTING.md for full guidelines.
# Quick development workflow
git checkout -b feature/my-feature
# ... make changes ...
make test && make lint
git commit -m "feat(scope): description"
git push origin feature/my-feature
# Open a Pull RequestThis project is licensed under GNU Lesser General Public License v3.0 — see LICENSE.
You CAN: Use SAGE in commercial/proprietary applications, modify and distribute it.
You MUST: Provide SAGE source code if distributed, allow library relinking, maintain LGPL-3.0 notices.
You DON'T need to: Open-source your application that uses SAGE.
Smart Contracts (contracts/ethereum/) are separately licensed under MIT License — see contracts/ethereum/LICENSE.
See also: LGPL-3.0 Full Text | INSTALL.md | NOTICE
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- RFC 9421 — HTTP Message Signatures
- RFC 9180 — HPKE
- A2A Protocol
- W3C DID Specification
- Ethereum Development Docs
- Kaia Network Docs
- RFC 9421 and RFC 9180 Working Groups
- A2A Protocol team
- Ethereum Foundation and Kaia Network
- Cloudflare CIRCL library
- Open source community
Built by the SAGE Team