SAGE - Secure Agent Guarantee Engine

Overview

SAGE (Secure Agent Guarantee Engine) is a comprehensive blockchain-based security framework for AI agent communication. It provides end-to-end encrypted, authenticated communication channels between AI agents using decentralized identity (DID) management, HPKE-based key agreement, and RFC 9421 HTTP Message Signatures.

What's New in v1.5.2 (2025-11-02)

KME/KEM Naming Fix & HPKE Synchronization - Patch Release

Naming Correction: Fixed KME → KEM typo throughout codebase (RFC 9180 compliance)
Smart Contract Update: Updated getKemPublicKey() and related interfaces
HPKE Synchronization: Improved KEM key resolution and error handling
Lint Fixes: Resolved ineffassign warnings in agent card client
Test Coverage: All 202 contract tests passing (100%)

Previous Release: v1.5.1 (2025-11-02)

Go 1.25.2 Upgrade & Enhanced Contract Tooling - Maintenance Release

Go Version Upgrade: Upgraded to Go 1.25.2 for latest security patches
Dependency Updates: 24 dependencies updated to latest compatible versions
Contract Deployment: New comprehensive deployment scripts for 12 networks
Developer Experience: Enhanced testing scripts with progress indicators
Documentation: Cleaned up contract documentation structure
100% Compatibility: All tests passing, fully backward compatible

Previous Release: v1.5.0 (2025-10-30)

AgentCardRegistry: Three-Phase Secure Registration - Major Release

Three-Phase Registration Flow: Enhanced security via commit-reveal pattern
- Phase 1 (Commit): Anti-front-running protection with commitment hash
- Phase 2 (Register): Time-windowed reveal (1-60 minutes)
- Phase 3 (Activate): Sybil-resistant activation delay (1+ hour)
- Economic Security: 0.01 ETH stake requirement (refunded upon activation)
New CLI Commands:
- sage-did commit - Initialize registration with stake
- sage-did register - Reveal commitment and register agent
- sage-did activate - Activate agent after delay
Enhanced Security Features:
- Commitment-based anti-front-running
- Time-locked activation prevents rapid spam
- Operator delegation system (ERC-721 style)
- Multi-key support (ECDSA, Ed25519, X25519)
Breaking Changes: Migration required from SageRegistryV4
- See AgentCardRegistry Migration Guide
- Legacy SageRegistryV4 deprecated but still functional

Previous Release: v1.4.0 (2024-10-27)

Development Dependencies Upgrade & Governance Testing - Minor Release

See CHANGELOG.md for complete release notes.

Live Deployments

Sepolia Testnet (SageRegistryV2 - Legacy):

SAGE Core System:
- SageRegistryV2: 0x487d45a678eb947bbF9d8f38a67721b13a0209BF
- ERC8004ValidationRegistry: 0x4D31A11DdE882D2B2cdFB9cCf534FaA55A519440
ERC-8004 Standalone:
- ERC8004IdentityRegistry: 0x02439d8DA11517603d0DE1424B33139A90969517

Note: SageRegistryV4 (Multi-Key Registry) is ready for deployment. See contracts/README.md for details.

Key Features

End-to-End Encrypted Handshake: HPKE (RFC 9180) based secure session establishment with X25519 key agreement
RFC 9421 Compliance: Complete HTTP message signature implementation for verifiable agent communication
Multi-Chain Support: Ethereum, Solana, and Kaia network integration for DID registry
Enhanced Security: Public key ownership verification with on-chain validation and key revocation
Multi-Algorithm Support: Ed25519, Secp256k1, and X25519 cryptographic operations
Multi-Key Agent Registry: SageRegistryV4 with support for up to 10 keys per agent (Ed25519, ECDSA) and atomic key rotation
Agent Metadata Management: Update agent information (name, description, endpoint, capabilities) with nonce-based replay protection
Session Management: Automatic session creation, key rotation, nonce tracking, and replay protection
Protocol-Agnostic Transport: HTTP, WebSocket, and MockTransport implementations with pluggable architecture
Zero External Dependencies: Removed a2a-go dependency for better maintainability and independence
Modular Architecture: Clean separation of concerns with extensible event-driven design
Comprehensive Testing: 85+ feature tests, integration tests, random fuzzing, and health monitoring

A2A Protocol Integration

SAGE provides native support for the Google A2A (Agent-to-Agent) protocol, enabling seamless interoperability with AI agent platforms that implement the A2A standard.

Available APIs

DID Generation Helpers (pkg/agent/did):
- GenerateAgentDIDWithAddress() - Create DIDs with owner address validation
- GenerateAgentDIDWithNonce() - Support multiple agents per owner
- DeriveEthereumAddress() - Derive Ethereum address from secp256k1 keys
Public Key Utilities (pkg/agent/did):
- MarshalPublicKey() / UnmarshalPublicKey() - Cross-platform key serialization
- Support for Ed25519, ECDSA/secp256k1, and X25519 keys
A2A Agent Cards (pkg/agent/did):
- GenerateA2ACard() - Export agent metadata as A2A-compliant JSON
- ValidateA2ACard() - Validate incoming A2A agent cards
- MergeA2ACard() - Import capabilities from A2A agents

Integration Guide

For detailed integration instructions with the sage-a2a-go project, see:

Quick Example

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 for verification
agentDID := did.GenerateAgentDIDWithAddress(did.ChainEthereum, ownerAddr)
// Result: "did:sage:ethereum:0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266"

// For multi-agent systems, use nonce
did1 := did.GenerateAgentDIDWithNonce(did.ChainEthereum, ownerAddr, 0)
did2 := did.GenerateAgentDIDWithNonce(did.ChainEthereum, ownerAddr, 1)

Project Structure

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 (NEW)
│   ├── client.go           # Handshake initiator implementation
│   ├── server.go           # Handshake responder with peer caching
│   └── types.go            # Invitation, Request, Response, Complete messages
├── hpke/                    # HPKE (RFC 9180) implementation (NEW)
│   ├── client.go           # HPKE sender (encapsulation)
│   ├── server.go           # HPKE receiver (decapsulation)
│   └── common.go           # Shared HPKE utilities
├── session/                 # Session and key management (NEW)
│   ├── 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 (NEW)
│   ├── 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 (NEW)
│   ├── checker.go          # Component health checks
│   └── server.go           # HTTP health endpoint
├── config/                  # Configuration management (NEW)
│   ├── 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 (NEW)
│   ├── 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

Installation

Prerequisites

Go 1.25 or higher (see GO_VERSION_REQUIREMENT.md)
Node.js 22+ and npm (for smart contract development)
Git

Quick Start

Clone the repository

git clone https://github.com/SAGE-X-project/sage.git
cd sage

Install Go dependencies

go mod download

Install smart contract dependencies

cd contracts/ethereum
npm install
cd ../..  # Return to root directory

Build the project

# Build all CLI tools for current platform
make build

# Build for all platforms (Linux, macOS, Windows on x86_64 and ARM64)
make build-all-platforms

# Build as C-compatible library
make build-lib              # Build for current platform
make build-lib-all          # Build for all platforms

# Create release packages with checksums
make release

# Or build individually
go build -o build/bin/sage-crypto ./cmd/sage-crypto
go build -o build/bin/sage-did ./cmd/sage-did
go build -o build/bin/deployment-verify ./cmd/deployment-verify

# Compile smart contracts
cd contracts/ethereum
npm run compile

See docs/BUILD.md for detailed build instructions including:

Cross-platform compilation (Linux, macOS, Windows)
Multi-architecture support (x86_64, ARM64)
Library builds (static .a, shared .so/.dylib/.dll)
C/C++, Python, and Rust integration examples

Configuration

Environment Setup

SAGE supports multiple configuration methods:

YAML Configuration File (Recommended)

Create config.yaml:

blockchain:
  ethereum:
    rpc_url: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
    contract_address: "0x..."
    chain_id: 1
  kaia:
    rpc_url: "https://public-en.node.kaia.io"
    contract_address: "0x..."
    chain_id: 8217

crypto:
  key_dir: "./keys"
  default_algorithm: "ed25519"

session:
  max_age: "1h"
  idle_timeout: "10m"
  cleanup_interval: "30s"

Environment Variables

# Network RPC Endpoints
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
KAIA_RPC_URL=https://public-en.node.kaia.io
KAIROS_RPC_URL=https://public-en-kairos.node.kaia.io

# Private Keys (use test keys only!)
PRIVATE_KEY=your_private_key_here
MNEMONIC=your_twelve_word_mnemonic_phrase_here

# Contract Addresses
SAGE_REGISTRY_ADDRESS=0x...

Hardhat Setup

SAGE uses two separate Hardhat installations for different purposes:

1. Root Hardhat (Go Integration Tests)

Location: /hardhat.config.js, /package.json, /package-lock.json
Purpose: Local blockchain for Go integration tests
Version: Hardhat 3.0.7 (latest)

Usage:

make test-integration  # Automatically starts Hardhat node
make blockchain-start  # Start blockchain manually
make blockchain-stop   # Stop blockchain

Configuration: Minimal setup (27 lines) with localhost network only

2. Contracts Hardhat (Solidity Development)

Location: /contracts/ethereum/hardhat.config.js
Purpose: Smart contract development, testing, and deployment
Version: Hardhat 2.26.3 (stable)

Usage:

cd contracts/ethereum
npm run compile     # Compile contracts
npm test           # Run contract tests
npm run deploy:local    # Deploy to local network
npm run deploy:kairos   # Deploy to Kaia testnet

Configuration: Full-featured (243 lines) with multiple networks, gas reporter, verification

Why Two Installations?

Separation of Concerns: Go tests don't depend on Solidity development environment
Independence: Each can use optimal Hardhat version for its purpose
Clean Testing: Go integration tests run from project root without affecting contract development

Usage

1. Generate Key Pairs

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

2. Register an AI Agent

# Register on Ethereum
./build/bin/sage-did register \
  --chain ethereum \
  --key keys/ethereum.key \
  --name "My AI Agent" \
  --endpoint "https://api.myagent.com" \
  --capabilities "chat,code,analysis"

# Resolve a DID
./build/bin/sage-did resolve did:sage:ethereum:0x...

# List agents by owner
./build/bin/sage-did list --owner 0x...

3. Update Agent Metadata

# Update agent information (V4 only)
./build/bin/sage-did update \
  --did did:sage:ethereum:0x... \
  --key keys/ethereum.key \
  --name "Updated Agent Name" \
  --endpoint "https://new-api.myagent.com" \
  --capabilities "chat,code,analysis,vision"

# Or use Go client

import (
    "github.com/sage-x-project/sage/pkg/agent/did"
    "github.com/sage-x-project/sage/pkg/agent/did/ethereum"
)

// Create V4 client
client, err := ethereum.NewEthereumClientV4(config)

// Update agent metadata
updates := map[string]interface{}{
    "name":        "Updated Agent Name",
    "description": "New description",
    "endpoint":    "https://new-api.myagent.com",
    "capabilities": map[string]interface{}{
        "version":  "2.0.0",
        "features": []string{"chat", "code", "analysis", "vision"},
    },
}

err = client.Update(ctx, agentDID, updates, keyPair)
// Nonce is automatically managed - supports multiple sequential updates

4. Transport Layer Selection

SAGE supports multiple transport protocols with automatic selection:

import (
    "github.com/sage-x-project/sage/pkg/agent/transport"
    "github.com/sage-x-project/sage/pkg/agent/transport/http"
    "github.com/sage-x-project/sage/pkg/agent/transport/websocket"
)

// Option 1: HTTP Transport
httpTransport := http.NewHTTPTransport("https://api.example.com")

// Option 2: WebSocket Transport
wsTransport := websocket.NewWebSocketTransport("wss://api.example.com")

// Option 3: MockTransport for testing
mockTransport := &transport.MockTransport{
    SendFunc: func(ctx context.Context, msg *transport.SecureMessage) (*transport.Response, error) {
        return serverHPKE.HandleMessage(ctx, msg)
    },
}

// Option 4: Automatic selection
selector := transport.NewDefaultSelector()
selector.AddTransport("http", httpTransport)
selector.AddTransport("ws", wsTransport)
selectedTransport, _ := selector.SelectTransport(ctx, targetDID)

5. Secure Handshake Protocol

The handshake establishes an end-to-end encrypted session between two agents:

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)

6. HPKE Encryption/Decryption

import (
    "github.com/sage-x-project/sage/pkg/agent/hpke"
    "github.com/sage-x-project/sage/pkg/agent/session"
)

// Get session from manager
sess, ok := sessionManager.GetByKeyID(keyID)

// Encryption
cipher, _ := sess.Encrypt(body)

// Decryption
plain, _ := sess.Decrypt(cipher)

7. Create RFC 9421 Signed Messages

import (
    "github.com/sage-x-project/sage/pkg/agent/core/rfc9421"
    "github.com/sage-x-project/sage/pkg/agent/session"
)

// Create HTTP message builder
builder := rfc9421.NewMessageBuilder()
msg := builder.
    Method("POST").
    Authority("api.example.com").
    Path("/api/v1/chat").
    Header("Content-Type", "application/json").
    Body([]byte(cipherRequestBody)).
    Build()

// Create verifier with session
verifier := rfc9421.NewHTTPVerifier(sess, sessionManager)

// Sign the message
signature, err := verifier.SignRequest(msg, sigName, []string{
    "@method", "@authority", "@path", "content-type", "content-digest",
}, privKey)

// Verify signature
err = verifier.VerifyRequest(req, pubKey, HTTPVerificationOptions)

Testing

Run Go Tests

# Run all tests with Makefile
make test

# Run all tests manually
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./pkg/agent/crypto/...
go test ./pkg/agent/did/...
go test ./pkg/agent/core/...
go test ./pkg/agent/hpke/...
go test ./pkg/agent/session/...
go test ./pkg/agent/transport/...

# Run E2E tests with MockTransport
go test -v ./pkg/agent/hpke -run TestE2E_HPKE_Handshake_MockTransport

# Run integration tests
make test-integration

# Run feature verification (85+ tests)
./tools/scripts/verify_all_features.sh

# Quick verification (5 checks)
./tools/scripts/quick_verify.sh

# Run quick tests (excluding slow integration tests)
make test-quick

Advanced Testing

# Random fuzzing tests
make random-test

# Benchmark tests
make bench

# Test with race detection
go test -race ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Development Scripts

# Verify all Makefile targets
./tools/scripts/verify_makefile.sh

# This script tests all major Makefile targets and reports:
# - PASS: Target executed successfully
# - FAIL: Target failed with error details
# - SKIP: Target skipped (e.g., requires external services)

Run Smart Contract Tests

cd contracts/ethereum

# Run all contract tests
npm test

# Run specific test suite
npm run test:v2

# Run with coverage
npm run coverage

# Run integration tests
npm run test:integration

Health Monitoring

# The health check endpoint provides system status
curl http://localhost:8080/health

# Response includes:
# - Component status (blockchain, session, crypto)
# - Session statistics
# - Uptime information
# - Degraded/healthy state

Smart Contract Features

SageRegistryV4 - Multi-Key Registry (v1.1.0)

The latest version introduces comprehensive multi-key support, agent metadata updates, and critical security enhancements:

Multi-Key Support: Up to 10 keys per agent with Ed25519 and ECDSA/secp256k1 algorithms
Agent Metadata Updates: Full support for updating agent information
- updateAgent(): Update name, description, endpoint, and capabilities
- getNonce(): Retrieve current nonce for replay protection
- Automatic nonce increment on each update
- Signature verification with registered keys
Atomic Key Rotation: Transaction-level atomic key replacement prevents incomplete rotation states
Complete Key Revocation: Full deletion from storage with nonce increment to invalidate old signatures
Public Key Ownership Verification: Dual verification (signature + address matching) prevents key theft attacks
Challenge-Response Authentication: Signature-based proof of key ownership for ECDSA keys
Ed25519 Approval Flow: Off-chain verification with contract owner approval for Ed25519 keys
Hook System: Extensible validation through before/after registration hooks
Gas Optimized: Efficient storage patterns with swap-and-pop for array operations

Security Fixes in V4:

CVE-SAGE-2025-001: Public key theft prevention via ownership verification
CVE-SAGE-2025-002: Atomic key rotation to prevent inconsistent states
CVE-SAGE-2025-003: Complete key revocation with storage deletion

See contracts/README.md for detailed smart contract documentation and V4_UPDATE_DEPLOYMENT_GUIDE.md for deployment instructions.

Gas Usage

Operation	Gas Used	USD (@ 30 gwei)
Register Agent	~620,000	~$48
Update Agent	~80,000	~$6
Revoke Key	~66,000	~$5
Deactivate Agent	~50,000	~$3.8

Supported Networks

Mainnet

Ethereum: Full support with ENS integration
Kaia (Cypress): Production deployment
Solana: In development

Testnet

Sepolia: Ethereum testnet
Kairos: Kaia testnet
Solana Devnet: Testing environment

Architecture Highlights

Handshake Protocol(HPKE, 1-RTT / 2-Phase)

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: (if configured) verify cookie early → verify DID signature → check replay/clock-skew/context → HPKE Open to recover exporterHPKE → generate ephS and compute ssE2E → derive seed = HKDF(exporterHPKE ∥ ssE2E, exportCtx) → create session.
Acknowledge (Server → Client)
- Sends: kid, ackTagB64 (key confirmation), ephS, and a signed server envelope.
- Client: verify ackTag (keys match) → verify server signature (identity + transcript binding) → bind kid ↔ session → derive c2s/s2c AEAD keys from seed and start the channel.

See docs/handshake/hpke-based-handshake-en.md for detailed protocol documentation.

Notes:
• If Cookies == nil, cookies are optional (missing cookie is allowed). If a verifier is set, a cookie is required.
• info/exportCtx are built via a canonical builder that includes ctxID, initDID, and respDID, preventing downgrade and cross-context reuse.

Session Management

Deterministic Session IDs: Derived from HKDF of shared secret
Directional Keys: Separate encryption/signing keys for client-to-server and server-to-client
Automatic Cleanup: Background goroutine removes expired sessions
Key ID Binding: Maps opaque key IDs to session IDs for RFC 9421 verification
Replay Protection: Nonce cache prevents replay attacks

Security Design

DID-Based Authentication: All agents verified through blockchain DID registry
Bootstrap Encryption: Initial messages encrypted with peer's Ed25519 public key
HPKE Session Keys: Ephemeral X25519 keys for forward secrecy
AEAD Encryption: ChaCha20-Poly1305 for session messages
HMAC Signatures: SHA-256 based message authentication
Challenge-Response: Prevents unauthorized key registration

Multi-Language Bindings

SAGE provides bindings for multiple programming languages:

Go: Native implementation
C/C++: Static and shared library bindings
Python: Web3.py based bindings + ctypes library integration
Rust: FFI bindings via static library
JavaScript/TypeScript: Ethers.js bindings
Java: JNI bindings (planned)

Smart Contract Bindings (Python Example)

from sage_contracts import SageRegistry

registry = SageRegistry(
    rpc_url="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
    contract_address="0x...",
    private_key="0x..."
)

# Register an agent
tx_hash = registry.register_agent(
    did="did:sage:ethereum:0x...",
    name="Python AI Agent",
    endpoint="https://api.example.com",
    public_key=public_key_bytes,
    capabilities=["chat", "analysis"]
)

C Library Integration

SAGE can be built as a C-compatible library for integration with other languages:

#include "libsage.h"

int main() {
    // Initialize SAGE library
    sage_init();

    // Generate Ed25519 key pair
    char public_key[128];
    char private_key[128];
    sage_generate_keypair(public_key, private_key);

    printf("Public Key: %s\n", public_key);

    // Cleanup
    sage_cleanup();
    return 0;
}

Compile with static library:

# Linux
gcc -o myapp myapp.c build/lib/linux-amd64/libsage.a

# macOS
clang -o myapp myapp.c build/lib/darwin-arm64/libsage.a

# Windows (MinGW)
x86_64-w64-mingw32-gcc -o myapp.exe myapp.c build/lib/windows-amd64/libsage.a

Python Library Integration (ctypes)

import ctypes
import os

# Load SAGE library
if os.name == 'nt':
    lib = ctypes.CDLL('libsage.dll')
elif os.uname().sysname == 'Darwin':
    lib = ctypes.CDLL('libsage.dylib')
else:
    lib = ctypes.CDLL('libsage.so')

# Initialize
lib.sage_init()

# Generate key pair
public_key = ctypes.create_string_buffer(128)
private_key = ctypes.create_string_buffer(128)
lib.sage_generate_keypair(public_key, private_key)

print(f"Public Key: {public_key.value.decode()}")

# Cleanup
lib.sage_cleanup()

See docs/BUILD.md for complete integration examples with C/C++, Python, Rust, and other languages.

Security Considerations

Private Key Management
- Never commit private keys to version control
- Use hardware wallets for production (via vault package)
- Implement key rotation policies
- Use OS keychain integration for sensitive keys
Smart Contract Security
- Contracts are upgradeable through proxy pattern
- Regular security audits recommended
- Bug bounty program available
- V2 includes 5-step key validation
Message Signature Verification
- Always verify signatures on the receiving end
- Check signature expiration timestamps
- Validate signer's DID status on-chain
- Use nonce cache to prevent replay attacks
Session Security
- Sessions auto-expire based on MaxAge and IdleTimeout
- Ephemeral keys provide forward secrecy
- Nonce tracking prevents replay attacks
- Secure memory cleanup on session close

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Code Style

Go: Follow standard Go formatting (gofmt, golangci-lint)
Solidity: Follow Solidity style guide
Use meaningful commit messages (conventional commits)
Add tests for new features (maintain >80% coverage)
Update documentation for API changes

Branch Protection

main branch requires PR approval
All PRs must pass CI checks
Direct pushes to main are not allowed

License

This project is licensed under the GNU Lesser General Public License v3.0 - see the LICENSE file for details.

What This Means for Users

You CAN:

Use SAGE in commercial applications
Use SAGE in proprietary software
Modify SAGE for your needs
Distribute SAGE

You MUST:

Provide SAGE source code if you distribute it (modified or not)
Allow users to replace/relink the SAGE library
Maintain LGPL-3.0 license notices
Provide installation/build instructions (see INSTALL.md)

You DON'T Need To:

⭕ Open-source your application that uses SAGE
⭕ Release your application under LGPL-3.0

Smart Contracts - Separate License

Note: Smart contracts in contracts/ethereum/ are separately licensed under MIT License to align with blockchain ecosystem standards. See contracts/ethereum/LICENSE for details.

Additional Resources

LGPL-3.0 Full Text: https://www.gnu.org/licenses/lgpl-3.0.html
Installation Guide: INSTALL.md
Third-Party Notices: NOTICE

Resources

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

Acknowledgments

RFC 9421 Working Group for HTTP Message Signatures specification
RFC 9180 Working Group for HPKE specification
A2A Protocol team for agent-to-agent communication framework
Ethereum Foundation for blockchain infrastructure
Kaia Network team for multi-chain support
Cloudflare CIRCL library for cryptographic primitives
Open source community for continuous feedback and contributions

Built by the SAGE Team

Documentation

Core Documentation

Documentation Index - Complete documentation catalog
Architecture Guide - System architecture and design patterns
Contributing Guide - How to contribute to SAGE
API Reference - HTTP and gRPC API documentation

Component Documentation

Handshake Protocol - HPKE handshake details
Smart Contracts - Ethereum and Solana contracts
Security Design - Security architecture
Testing Guide - Testing strategies and best practices
Benchmark Guide - Performance benchmarking

Development

Build Instructions - Compilation and installation
CI/CD Pipeline - Continuous integration workflows
Coding Guidelines - Code quality standards
Code Review Checklist - PR review guidelines

Name		Name	Last commit message	Last commit date
Latest commit History 145 Commits
.github		.github
api		api
cmd		cmd
contracts		contracts
deployments		deployments
docs		docs
examples		examples
internal		internal
lib		lib
pkg		pkg
scripts/test		scripts/test
sdk		sdk
tests		tests
tools		tools
.dockerignore		.dockerignore
.env.e2e.example		.env.e2e.example
.env.example		.env.example
.gitignore		.gitignore
.gitleaksignore		.gitleaksignore
.golangci.yml		.golangci.yml
.gosec.json		.gosec.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
INSTALL.md		INSTALL.md
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
VERSION		VERSION
codecov.yml		codecov.yml
go.mod		go.mod
go.sum		go.sum
package-lock.json		package-lock.json

License

SAGE-X-project/sage

Folders and files

Latest commit

History

Repository files navigation

SAGE - Secure Agent Guarantee Engine

Overview

What's New in v1.5.2 (2025-11-02)

Previous Release: v1.5.1 (2025-11-02)

Previous Release: v1.5.0 (2025-10-30)

Previous Release: v1.4.0 (2024-10-27)

Live Deployments

Key Features

A2A Protocol Integration

Available APIs

Integration Guide

Quick Example

Project Structure

Installation

Prerequisites

Quick Start

Configuration

Environment Setup

Hardhat Setup

1. Root Hardhat (Go Integration Tests)

2. Contracts Hardhat (Solidity Development)

Usage

1. Generate Key Pairs

2. Register an AI Agent

3. Update Agent Metadata

4. Transport Layer Selection

5. Secure Handshake Protocol

6. HPKE Encryption/Decryption

7. Create RFC 9421 Signed Messages

Testing

Run Go Tests

Advanced Testing

Development Scripts

Run Smart Contract Tests

Health Monitoring

Smart Contract Features

SageRegistryV4 - Multi-Key Registry (v1.1.0)

Gas Usage

Supported Networks

Mainnet

Testnet

Architecture Highlights

Handshake Protocol(HPKE, 1-RTT / 2-Phase)

Session Management

Security Design

Multi-Language Bindings

Smart Contract Bindings (Python Example)

C Library Integration

Python Library Integration (ctypes)

Security Considerations

Contributing

Development Setup

Code Style

Branch Protection

License

What This Means for Users

Smart Contracts - Separate License

Additional Resources

Resources

Support

Acknowledgments

Documentation

Core Documentation

Component Documentation

Development

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages