PostFiat SDK: Protected Content and Auditability Extension for A2A gRPC¶

graph TB
    subgraph "Agent Registration"
        Agent[PostFiat Agent]
        DirectReg[Direct Ledger Registration]
        RegistryReg[Registry Service Registration]

        Agent --> DirectReg
        Agent --> RegistryReg
        DirectReg --> XRPL[XRPL Ledger]
        RegistryReg --> Registry[Registry Service]
        Registry --> XRPL
    end

    subgraph "Communication Paths"
        A2APath[A2A gRPC Path<br/>Performance/Real-time]
        LedgerPath[Ledger Transaction Path<br/>Auditability/Compliance]

        Agent --> A2APath
        Agent --> LedgerPath
        LedgerPath --> XRPL
    end

    subgraph "Client Discovery"
        Client[Client]
        TrustRegistry[Trust Registry Service]
        VerifyDirect[Verify On-Chain Directly]

        Client --> TrustRegistry
        Client --> VerifyDirect
        TrustRegistry --> Registry
        VerifyDirect --> XRPL
    end

    style XRPL fill:#f9f,stroke:#333,stroke-width:4px
    style DirectReg fill:#e1f5fe
    style LedgerPath fill:#e8f5e8

// A2A's core message structure - we use this as-is
message Message {
  string message_id = 1;
  string context_id = 2;      // A2A conversation threading
  string task_id = 3;         // A2A task management
  Role role = 4;              // ROLE_USER or ROLE_AGENT
  repeated Part content = 5;  // ← PostFiat protected content goes here
  google.protobuf.Struct metadata = 6;
  repeated string extensions = 7;  // ← PostFiat extension URI
}

// A2A's content container - we use DataPart for structured protected content
message Part {
  oneof part {
    string text = 1;
    FilePart file = 2;
    DataPart data = 3;  // ← PostFiat protected envelopes
  }
}

// A2A's agent capabilities - we extend this
message AgentCapabilities {
  bool streaming = 1;
  bool push_notifications = 2;
  repeated AgentExtension extensions = 3;  // ← PostFiat protected content extension
}

service A2AService {
  // We use these A2A methods as-is
  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
  rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse);
  rpc GetTask(GetTaskRequest) returns (Task);
  rpc GetAgentCard(GetAgentCardRequest) returns (AgentCard);
}

def generate_a2a_context_id(agent_id: str, session_info: str) -> str:
    """Generate collision-resistant A2A context_id"""
    import uuid
    import hashlib

    # Option 1: Namespaced UUID
    namespace_uuid = uuid.uuid5(uuid.NAMESPACE_DNS, agent_id)
    context_uuid = uuid.uuid5(namespace_uuid, session_info)
    return f"{agent_id}::{context_uuid}"

    # Option 2: Cryptographic hash
    content = f"{agent_id}::{session_info}::{uuid.uuid4()}"
    return f"ctx_{hashlib.sha256(content.encode()).hexdigest()[:16]}"

# Example usage
a2a_context_id = generate_a2a_context_id(
    agent_id="postfiat_research_agent_001",
    session_info="alice_regulatory_analysis_2024"
)
# Result: "postfiat_research_agent_001::a1b2c3d4-e5f6-7890-abcd-ef1234567890"

// PostFiat extension for A2A
message PostFiatExtension {
  // PostFiat envelope (from PostFiat SDK messages.proto)
  Envelope envelope = 1;

  // Content address (hash of content) - available immediately for content-addressable encryption
  string content_address = 2;

  // Ledger transaction hash - assigned by ledger node after submission (not available at creation time)
  optional string ledger_transaction_hash = 3;

  // Context DAG processing configuration
  PostFiatContextProcessingConfig processing_config = 4;
}

// PostFiat-specific type (not part of A2A)
message PostFiatContextProcessingConfig {
  // Maximum depth for context DAG traversal
  uint32 max_context_depth = 1;

  // Whether to include opaque node metadata in responses
  bool include_opaque_nodes = 2;

  // Processing timeout for context resolution
  uint32 timeout_seconds = 3;
}

// How PostFiat protected content integrates with A2A Message
// This uses the actual A2A Message structure from a2a.proto
SendMessageRequest {
  Message request = 1 {
    string message_id = "msg_12345";
    string context_id = "ai_ethics_research_2024";  // A2A conversation threading
    string task_id = "task_67890";                  // A2A task management
    Role role = ROLE_USER;                          // From A2A enum

    // PostFiat envelope content
    repeated Part content = [
      {
        DataPart data = {
          // PostFiat extension data as google.protobuf.Struct
          "postfiat_envelope": {
            "envelope": {
              "version": 1,
              "content_hash": "sha256:abc123...",
              "encryption": "PROTECTED",
              "public_references": [...],
              "message": "encrypted_content_bytes"
            },
            "content_address": "sha256:envelope_content_hash...",  // Available immediately
            // "xrpl_transaction_hash": "tx_def456...",  // Added after ledger confirmation
            "processing_config": {
              "max_context_depth": 10,
              "include_opaque_nodes": true,
              "timeout_seconds": 30
            }
          }
        }
      }
    ];

    // A2A metadata + PostFiat metadata
    google.protobuf.Struct metadata = {
      "postfiat_version": "1.0.0",
      "envelope_enabled": true
    };

    // PostFiat extension declaration
    repeated string extensions = [
      "https://postfiat.org/extensions/envelope/v1"
    ];
  };

  // A2A configuration
  SendMessageConfiguration configuration = {
    repeated string accepted_output_modes = ["text/plain", "application/json"];
    bool blocking = true;
  };
}

// PostFiat agent capability attestation written directly to XRPL memo
message PostFiatAgentAttestation {
  // Agent identity
  string agent_id = "agent_postfiat_research_001";
  string agent_name = "PostFiat Research Assistant";
  string agent_description = "AI agent with envelope-based context sharing";

  // Service endpoints
  string grpc_endpoint = "https://agent.postfiat.org:443";
  string ledger_address = "rPostFiatAgent123...";

  // PostFiat capabilities
  PostFiatCapabilities postfiat_capabilities = {
    string extension_uri = "https://postfiat.org/extensions/envelope/v1";
    uint32 max_context_depth = 10;
    repeated string supported_encryption_modes = ["NONE", "PROTECTED", "PUBLIC_KEY"];
    string xrpl_network = "mainnet";
    bool context_dag_traversal = true;
    bool immutable_storage = true;
  };

  // Attestation metadata
  int64 attestation_timestamp = 1704067200;
  string attestation_signature = "agent_signature_proof";
}

// XRPL Transaction with agent attestation
XRPLTransaction {
  account: "rPostFiatAgent123...",
  transaction_type: "Payment",
  destination: "rPostFiatRegistry456...",
  amount: "1",  // Minimal XRP for transaction
  memos: [
    {
      memo_type: "postfiat/agent-attestation/v1",
      memo_data: base64_encode(PostFiatAgentAttestation)
    }
  ]
}

// A2A AgentCard with PostFiat extension + ledger backing
AgentCard {
  string protocol_version = "1.0";  // A2A protocol version
  string name = "PostFiat Research Assistant";
  string description = "AI agent with envelope-based context sharing and XRPL attestation";
  string url = "https://agent.postfiat.org";
  string preferred_transport = "GRPC";

  AgentProvider provider = {
    string url = "https://postfiat.org";
    string organization = "PostFiat";
  };

  string version = "1.0.0";
  string documentation_url = "https://docs.postfiat.org";

  // A2A capabilities extended with PostFiat + ledger attestation
  AgentCapabilities capabilities = {
    bool streaming = true;
    bool push_notifications = true;

    repeated AgentExtension extensions = [
      {
        string uri = "https://postfiat.org/extensions/envelope/v1";
        string description = "PostFiat envelope with context DAG traversal and XRPL persistence";
        bool required = false;
        google.protobuf.Struct params = {
          "max_context_depth": 10,
          "supported_encryption_modes": ["NONE", "PROTECTED", "PUBLIC_KEY"],
          "xrpl_network": "mainnet",
          "context_dag_traversal": true,
          "immutable_storage": true,
          // Ledger attestation reference
          "ledger_attestation_tx": "tx_abc123...",
          "ledger_address": "rPostFiatAgent123..."
        };
      }
    ];
  };

  repeated AgentSkill skills = [
    {
      string id = "contextual_analysis";
      string name = "Contextual Analysis with PostFiat Envelopes";
      string description = "Analyze queries using PostFiat context DAG traversal with ledger attestation";
      repeated string tags = ["analysis", "context", "privacy", "auditable"];
      repeated string examples = [
        "Analyze this research with my private context (auditable)",
        "What are the implications given my collaboration history? (compliance mode)"
      ];
      repeated string input_modes = ["text/plain", "application/postfiat-envelope"];
      repeated string output_modes = ["text/plain", "application/json"];
    }
  ];
}

class PostFiatAgentDiscovery:
    """Client can choose verification method"""

    async def discover_agents_via_registry(self, capabilities: List[str]) -> List[AgentCard]:
        """Trust registry service aggregation"""
        registry_client = A2ARegistryClient()
        return await registry_client.find_agents_with_capabilities(capabilities)

    async def discover_agents_via_ledger(self, capabilities: List[str]) -> List[PostFiatAgentAttestation]:
        """Verify directly from XRPL ledger"""
        xrpl_client = XRPLClient()

        # Query XRPL for agent attestation transactions
        attestation_txs = await xrpl_client.get_transactions_with_memo_type(
            "postfiat/agent-attestation/v1"
        )

        # Parse and filter by capabilities
        agents = []
        for tx in attestation_txs:
            attestation = self.parse_agent_attestation(tx.memo_data)
            if self.agent_supports_capabilities(attestation, capabilities):
                agents.append(attestation)

        return agents

    async def verify_agent_attestation(self, agent_id: str) -> bool:
        """Cross-verify registry claims against ledger"""
        # Get agent info from registry
        registry_info = await self.discover_agents_via_registry([])

        # Get attestation from ledger
        ledger_attestation = await self.discover_agents_via_ledger([])

        # Verify consistency
        return self.verify_consistency(registry_info, ledger_attestation)

sequenceDiagram
    participant Alice as Alice (A2A Client)
    participant A2A as A2A gRPC Service
    participant LLM as LLM Agent (PostFiat-enabled)
    participant Registry as Registry Service

    Note over Alice: Alice discovers agent via registry
    Alice->>Registry: GetAgentCard(capabilities=["postfiat-envelope"])
    Registry-->>Alice: Return LLM agent card with PostFiat support

    Note over Alice: Alice prepares A2A message with PostFiat context
    Alice->>Alice: Create A2A SendMessageRequest
    Alice->>Alice: Embed PostFiat envelope in Message.content[DataPart]
    Alice->>Alice: Include ContextReferences in envelope

    Alice->>A2A: SendMessage(request with PostFiat extension)
    A2A->>LLM: Route message to LLM agent

    Note over LLM: LLM processes PostFiat envelope
    LLM->>LLM: Extract PostFiat extension from A2A Message.content
    LLM->>LLM: Parse PostFiat envelope and build context DAG
    LLM->>LLM: Generate response with PostFiat envelope

    LLM->>A2A: Return A2A SendMessageResponse with PostFiat data
    A2A->>Alice: Deliver response immediately

    Note over Alice: Alice receives contextual advice (fast, no audit trail)

sequenceDiagram
    participant Alice as Alice (Client)
    participant XRPL as XRPL Ledger
    participant LLM as LLM Agent (PostFiat-enabled)
    participant Storage as Content Storage

    Note over Alice: Alice discovers agent via ledger verification
    Alice->>XRPL: Query agent attestation transactions
    XRPL-->>Alice: Return PostFiat agent attestations
    Alice->>Alice: Verify agent capabilities from ledger

    Note over Alice: Alice writes query to ledger
    Alice->>Alice: Create PostFiat envelope with context DAG
    Alice->>XRPL: Write transaction with PostFiat envelope in memo
    XRPL-->>Alice: Return transaction hash

    Note over LLM: LLM monitors ledger for new queries
    LLM->>XRPL: Monitor for transactions to agent address
    XRPL-->>LLM: Return new transaction with PostFiat envelope

    LLM->>LLM: Parse PostFiat envelope from transaction memo
    LLM->>LLM: Build context dependency graph

    loop For each ContextReference
        LLM->>Storage: Fetch encrypted content by content_hash
        Storage-->>LLM: Return encrypted content

        alt Has decryption_key
            LLM->>LLM: Decrypt content and cache key
            LLM->>LLM: Extract nested ContextReferences
        else No decryption_key
            LLM->>LLM: Mark as opaque node in DAG
        end
    end

    LLM->>LLM: Analyze complete accessible context
    LLM->>LLM: Generate response with PostFiat envelope

    LLM->>XRPL: Write response transaction with PostFiat envelope
    XRPL-->>LLM: Return response transaction hash

    Note over Alice: Alice monitors ledger for response
    Alice->>XRPL: Monitor for response transactions
    XRPL-->>Alice: Return response transaction with PostFiat envelope
    Alice->>Alice: Parse response from transaction memo

    Note over Alice: Alice receives contextual advice with complete audit trail

sequenceDiagram
    participant Alice as Alice (Client)
    participant A2A as A2A gRPC Service
    participant LLM as LLM Agent (PostFiat-enabled)
    participant XRPL as XRPL Ledger

    Note over Alice: Alice uses A2A for speed + ledger for audit

    Alice->>A2A: SendMessage(PostFiat envelope, audit_required=true)
    A2A->>LLM: Route message to LLM agent

    par A2A Processing
        LLM->>LLM: Process PostFiat envelope via A2A
        LLM->>A2A: Return immediate response
        A2A->>Alice: Deliver fast response
    and Parallel Ledger Attestation
        LLM->>XRPL: Write interaction attestation to ledger
        XRPL-->>LLM: Return attestation transaction hash
        LLM->>A2A: Include attestation hash in response metadata
    end

    Note over Alice: Alice gets immediate response + audit proof
    Alice->>Alice: Verify audit trail via attestation hash
    Alice->>XRPL: Optional: Verify attestation transaction
    XRPL-->>Alice: Confirm interaction was recorded

graph TB
    subgraph "A2A Context: ai_ethics_research_2024"
        subgraph "A2A Message 1: Alice's Query"
            Q[PostFiat Envelope<br/>PROTECTED<br/>Key: alice_query_123<br/>XRPL: tx_abc123]
        end

        subgraph "PostFiat Context DAG (within message content)"
            subgraph "Accessible Context Layer"
                A[AI Ethics Research<br/>PROTECTED<br/>Key: research_456<br/>XRPL: tx_def456]
                B[Regulatory Framework<br/>PROTECTED<br/>Key: shared_789<br/>XRPL: tx_ghi789]
                C[Industry Standards<br/>NONE<br/>Public<br/>XRPL: tx_jkl012]
            end

            subgraph "Deep Context Layer"
                D[Alice's Private Notes<br/>PROTECTED<br/>Key: alice_private_abc<br/>XRPL: tx_mno345]
                E[Bob's Analysis<br/>PROTECTED<br/>Key: bob_shared_def<br/>XRPL: tx_pqr678]
                F[Carol's Legal Review<br/>PROTECTED<br/>Key: shared_789<br/>XRPL: tx_stu901]
                I[Deep Reference<br/>PROTECTED<br/>Key: shared_789 ← known key!<br/>XRPL: tx_abc890]
            end

            subgraph "Opaque Nodes (Envelope Accessible)"
                G[Confidential Legal Doc<br/>PROTECTED<br/>Key: shared_ABC ← No access<br/>XRPL: tx_vwx234]
                H[Company Internal<br/>PUBLIC_KEY<br/>Not for LLM<br/>XRPL: tx_yz567]
            end
        end
    end

    Q --> A
    Q --> B
    Q --> C

    A --> D
    A --> E
    B --> F
    B --> G
    C --> H

    G --> I

    style Q fill:#e1f5fe
    style A fill:#e8f5e8
    style B fill:#e8f5e8
    style C fill:#e8f5e8
    style D fill:#f3e5f5
    style E fill:#f3e5f5
    style F fill:#f3e5f5
    style G fill:#ffebee
    style H fill:#ffebee
    style I fill:#f3e5f5

flowchart TD
    Start[Receive A2A SendMessageRequest] --> CheckExt[Check for PostFiat extension]
    CheckExt -->|Has extension| Extract[Extract PostFiat DataPart]
    CheckExt -->|No extension| StandardA2A[Process as standard A2A message]

    Extract --> ParseEnvelope[Parse PostFiat envelope]
    ParseEnvelope --> BuildQueue[Build ContextReference processing queue]

    BuildQueue --> ProcessNext{More contexts to process?}
    ProcessNext -->|Yes| GetContent[Fetch content by hash from XRPL/Storage]
    ProcessNext -->|No| Analyze[Analyze complete context]

    GetContent --> HasKey{Has decryption_key?}

    HasKey -->|Yes| Decrypt[Decrypt content]
    HasKey -->|No| MarkOpaque[Mark as opaque node]

    Decrypt --> CacheKey[Cache key for reuse]
    CacheKey --> ExtractNested[Extract nested ContextReferences]
    ExtractNested --> AddToQueue[Add to processing queue]
    AddToQueue --> ProcessNext

    MarkOpaque --> RecordStructure[Record DAG structure]
    RecordStructure --> ProcessNext

    Analyze --> GenerateResponse[Generate contextual response]
    GenerateResponse --> CreateA2AResponse[Create A2A SendMessageResponse]
    CreateA2AResponse --> StoreXRPL[Store interaction on XRPL]
    StoreXRPL --> SendA2AResponse[Send A2A response]
    SendA2AResponse --> End[Complete]

    StandardA2A --> End

class PostFiatA2AAgent:
    """A2A agent with PostFiat envelope capabilities"""

    def __init__(self):
        self.key_cache = {}  # content_hash -> decryption_key
        self.content_cache = {}  # content_hash -> decrypted_content
        self.context_dag = {}  # content_hash -> PostFiatContextNode

    async def handle_a2a_message(self, request: SendMessageRequest) -> SendMessageResponse:
        """Process A2A message with potential PostFiat extension"""

        message = request.request

        # Check for PostFiat extension
        if "https://postfiat.org/extensions/envelope/v1" not in message.extensions:
            return await self.handle_standard_a2a_message(request)

        # Extract PostFiat envelope from DataPart
        postfiat_data = None
        for part in message.content:
            if part.HasField('data'):
                data_struct = part.data.data
                if 'postfiat_envelope' in data_struct:
                    postfiat_data = data_struct['postfiat_envelope']
                    break

        if not postfiat_data:
            return await self.handle_standard_a2a_message(request)

        # Process PostFiat envelope
        envelope = self.parse_envelope(postfiat_data['envelope'])
        content_address = postfiat_data.get('content_address')
        processing_config = postfiat_data.get('processing_config', {})

        # Verify content address matches envelope
        computed_address = self.compute_content_address(envelope)
        if content_address != computed_address:
            raise ValueError(f"Content address mismatch: {content_address} != {computed_address}")

        # Build context DAG
        context_dag = await self.build_context_dag(
            envelope.public_references,
            max_depth=processing_config.get('max_context_depth', 10),
            timeout=processing_config.get('timeout_seconds', 30)
        )

        # Generate response
        response_content = await self.generate_contextual_response(
            envelope, context_dag, message.context_id
        )

        # Create response content address
        response_address = self.compute_content_address(response_content)

        # Store on XRPL (async - transaction hash not immediately available)
        xrpl_tx_hash = await self.store_on_xrpl(message, response_content)

        # Create A2A response
        response_message = Message(
            message_id=f"response_{message.message_id}",
            context_id=message.context_id,
            task_id=message.task_id,
            role=Role.ROLE_AGENT,
            content=[
                Part(data=DataPart(data=Struct(fields={
                    'postfiat_envelope': Value(struct_value=Struct(fields={
                        'envelope': self.envelope_to_struct(response_content),
                        'content_address': Value(string_value=response_address),
                        'xrpl_transaction_hash': Value(string_value=xrpl_tx_hash),  # May be None initially
                        'context_dag_summary': self.dag_summary_to_struct(context_dag)
                    }))
                })))
            ],
            extensions=["https://postfiat.org/extensions/envelope/v1"]
        )

        return SendMessageResponse(msg=response_message)

    def compute_content_address(self, envelope: Envelope) -> str:
        """Compute content-addressable hash for envelope"""
        import hashlib
        envelope_bytes = envelope.SerializeToString()
        return f"sha256:{hashlib.sha256(envelope_bytes).hexdigest()}"

# PostFiat SDK depends on A2A gRPC libraries
dependencies = [
    "a2a-grpc-python>=1.0.0",  # A2A gRPC client/server
    "postfiat-envelope>=1.0.0",  # PostFiat envelope system
    "xrpl-py>=2.0.0",  # XRPL blockchain integration
]

class PostFiatA2AService(A2AService):
    """PostFiat-enabled A2A service"""

    def __init__(self):
        super().__init__()
        self.register_extension("https://postfiat.org/extensions/envelope/v1")
        self.envelope_processor = PostFiatEnvelopeProcessor()
        self.xrpl_client = XRPLClient()