Gao SDK - Developer Layer

Canonical integration interface for Gao Internet protocols

Gao SDK Is

A protocol integration toolkit
A capability-aware execution wrapper
A receipt validation library
A deterministic routing interface
A cross-layer developer bridge

Design Principles#

1. Non-Custodial by Design

The SDK:

Does not hold private keys
Does not pool funds
Does not execute unsigned transactions
Does not modify protocol receipts

All write actions require:

Capability validation (Layer 8 — AI OS)
Policy enforcement (Layer 4 — Payment)
Explicit user signature

2. Deterministic Execution

Given identical inputs, the SDK must produce:

Identical routing selection
Identical policy evaluation result
Identical receipt structure
Identical canonical audit event

Randomized behavior requires seed logging for reproducibility.

3. Receipt-Native Architecture

All state-changing operations emit canonical receipts.

SDK utilities include:

Schema verification
Signature binding validation
Replay protection
Finality confirmation checks

Core Modules#

1. Workspace Integration Module (Layer 1)

Scope clarification only.

Implements:

GAO-AIP-01 (Agent Identity)
GAO-AIP-05 (Policy Engine)
GAO-AIP-06 (Risk Classification)

Provides programmable interface for:

Policy configuration
Agent capability management
Governance read access
Activity export utilities

Workspace remains UI layer. SDK exposes integration hooks only.

2. Browser Integration Module (Layer 2)

Provides:

Domain resolution helpers
x402 header injection utilities
Receipt validation tools
Runtime-safe execution wrappers

Browser remains gateway runtime.

3. Domain Module (Layer 5)

Implements:

GAO-AIP-01 (Agent Identity)
GAO-AIP-02 (Reputation Model)

Functions:

Resolve .gao identities
Retrieve multi-chain address mappings
Verify domain ownership signatures
Load agent metadata

Example:

const domain = await gao.domain.resolve("alice.gao");

Resolution is read-only and publicly verifiable.

4. Payment Module (Layer 4)

Implements:

GAO-AIP-03 (Commerce Binding)
GAO-AIP-04 (Wallet & Budget Model)
GAO-AIP-05 (Policy Engine)
GAO-AIP-06 (Risk Classification)

Functions:

Create payment intent
Validate capability
Route currency deterministically
Generate canonical receipt
Verify settlement finality

Example:

const intent = await gao.payment.createIntent({...});

SDK does not sign transactions.

4.1 x402 Sub-Module

Namespace:

gao.payment.x402.*

Supports:

HTTP 402 challenge parsing
Proof header generation
Retry wrapper logic
Receipt validation

x402 is part of Settlement layer, not standalone.

5. Network Module (Layer 6)

Implements:

GAO-AIP-12 (Execution Node Tiers)
Deterministic routing rules

Functions:

Fetch routing candidates
Retrieve node performance metrics
Inspect PoC eligibility
Validate relay path integrity

Example:

const route = await gao.network.selectRoute({...});

SDK assists integration only. Routing consensus remains protocol-controlled.

6. DePIN Module (Layer 7)

Implements:

GAO-AIP-09 (Runtime Standard)
GAO-AIP-11 (Memory Model)
GAO-AIP-12 (Compute Routing)

Functions:

Upload storage payload
Submit compute job
Retrieve execution receipt
Validate node proof

Example:

const job = await gao.depin.compute.run({...});

Execution occurs at node level. SDK verifies receipt only.

7. AI OS Capability Module (Layer 8)

Implements:

GAO-AIP-01 through GAO-AIP-13

Functions:

Request capability
Validate expiration
Enforce domain scope
Check risk tier compatibility
Validate policy snapshot hash

Capability example:

{
  "capability": "payment:send",
  "identity": "alice.gao",
  "max_amount": "25",
  "expires_at": "2026-03-01T00:00:00Z"
}

Capability must be validated before invoking settlement.

Error Handling Standard#

All SDK errors follow numeric format GAO-XXXX.

Settlement succeeded but receipt emission failed:

SDK reconstructs receipt from chain data
Emits canonical recovery receipt
Logs deterministic recovery hash

Extended Error Reference: For the complete SDK error catalog, see: → dev.gao.systems/docs/sdk/errors

Versioning Strategy#

SDK follows:

Semantic Versioning (SemVer)
AIP compatibility matrix
Feature flag gating
Minimum two minor version deprecation window

Breaking changes require:

Major version bump
Governance notice
Migration documentation

Network Behavior at Different Usage Levels#

Low usage:

Basic routing
Minimal automation

Medium usage:

Active cross-layer integration
Expanded M2M payments

High usage:

Full stack orchestration
Deterministic multi-agent workflows

Important: Usage scenarios are illustrative only. No adoption level is guaranteed.

Compliance Positioning#

Gao SDK is infrastructure software.

It does NOT:

Provide financial services
Custody user assets
Generate passive income
Guarantee revenue
Represent an investment contract

All economic outcomes depend on:

Independent infrastructure operation
Market demand
Verified service execution

Final regulatory interpretation depends on jurisdiction.

Legal Disclosures#

Not Investment Advice

This documentation is informational only.

It does not constitute:

Investment advice
Financial recommendation
Legal counsel
Offer of securities

Operational Risks

Using Gao SDK involves:

Smart contract risks
Integration errors
Network variability
Regulatory uncertainty

No guarantees exist regarding:

Adoption levels
Payment volume
Economic outcomes

Jurisdictional Responsibility

Developers are responsible for ensuring compliance with applicable laws in their jurisdiction.

Protocol Changes

Specifications, schemas, and parameters may evolve via governance processes. Changes are public, time-locked, and bounded.