delegation.proto

syntax = "proto3";

package umbra.v1;

option go_package = "github.com/umbra-research/umbra-zk/gen/go/umbra/v1";

// ──────────────────────────────────────────────
// Core Domain Messages
// ──────────────────────────────────────────────

// DelegationGrant is the "digital power of attorney" signed by the Sovereign
// Owner authorizing an AI Agent to act within defined constraints.
message DelegationGrant {
  bytes  grant_id         = 1;  // Unique nonce to prevent replay attacks
  bytes  root_public_key  = 2;  // EdDSA public key of the Sovereign Owner
  bytes  agent_public_key = 3;  // EdDSA public key of the Agent (Session Key)
  uint32 scope_mask       = 4;  // Bitmask: 0x01=Trade, 0x02=Transfer, 0x04=Withdraw
  repeated bytes asset_whitelist = 5;  // Allowed contract addresses (e.g., [USDC, TBILL])
  bytes  spending_limit   = 6;  // Max cumulative value allowed (BigInt encoded)
  uint64 expiration       = 7;  // Unix timestamp after which the grant is invalid
  bytes  revocation_root  = 8;  // Merkle root of the revocation registry at signing time
}

// MerkleProof contains the path data for SMT non-membership verification.
message MerkleProof {
  bytes          leaf       = 1;  // The leaf value (should be zero for non-membership)
  repeated bytes path       = 2;  // Sibling hashes along the Merkle path
  repeated bool  directions = 3;  // Path directions (false=left, true=right)
  bytes          root       = 4;  // The expected Merkle root
}

// TradePayload describes the trade the Agent wants to execute.
message TradePayload {
  bytes  asset_id     = 1;  // Contract address of the asset
  bytes  amount       = 2;  // Trade amount (BigInt encoded)
  bytes  recipient    = 3;  // Destination address
  uint64 nonce        = 4;  // Trade nonce for ordering
  uint64 timestamp    = 5;  // Execution timestamp
}

// ──────────────────────────────────────────────
// RPC Request / Response
// ──────────────────────────────────────────────

// ProofRequest is sent by the Agent to the Prover to generate a ZK proof.
message ProofRequest {
  DelegationGrant grant           = 1;
  TradePayload    trade_payload   = 2;
  bytes           agent_signature = 3;  // EdDSA signature over TradePayload
  bytes           grant_signature = 4;  // EdDSA signature over DelegationGrant by Root
  MerkleProof     compliance_proof = 5; // Sanctions SMT non-membership proof
}

// ProofResponse contains the generated ZK proof and public inputs.
message ProofResponse {
  bytes  proof          = 1;  // Serialized Groth16 proof
  bytes  public_inputs  = 2;  // Serialized public witness
  string status         = 3;  // "OK" or error description
  uint64 generation_ms  = 4;  // Proof generation time in milliseconds
}

// VerifyRequest asks the service to verify an existing proof.
message VerifyRequest {
  bytes proof         = 1;
  bytes public_inputs = 2;
}

// VerifyResponse returns the verification result.
message VerifyResponse {
  bool   valid   = 1;
  string message = 2;
}

// ──────────────────────────────────────────────
// gRPC Service Definition
// ──────────────────────────────────────────────

// ProverService provides high-performance ZK proof generation and verification.
// Transport: gRPC over HTTP/2 for <25ms latency with multiplexed streams.
service ProverService {
  // GenerateProof creates a Groth16 ZK proof for a delegated trade.
  rpc GenerateProof(ProofRequest) returns (ProofResponse);

  // VerifyProof checks whether a proof is valid against the verification key.
  rpc VerifyProof(VerifyRequest) returns (VerifyResponse);

  // StreamProofs allows high-frequency agents to submit a stream of proof requests.
  rpc StreamProofs(stream ProofRequest) returns (stream ProofResponse);
}