openapi.yaml

openapi: 3.1.0
info:
  title: XGuard Analysis API
  version: 7.0.0-preview
  description: Explainable pre-sign analysis for X Layer with an integrity-verifiable Analysis Receipt, optional Ed25519 deployment-key attestation, and deterministic wallet/dApp policy action.
paths:
  /api/analyze:
    post:
      summary: Analyze a proposed X Layer transaction
      description: Read-only analysis. This operation never connects a wallet, signs, or broadcasts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeRequest'
      responses:
        '200':
          description: Completed analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeResponse'
        '400':
          description: Invalid request
        '413':
          description: Request body too large
        '429':
          description: Rate limited
  /api/attestation-key:
    get:
      summary: Resolve this deployment's safe public attestation key
      description: Returns only derived public SPKI material and availability metadata. Private key material is never returned.
      responses:
        '200':
          description: Public deployment attestation-key state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestationKeyResponse'
components:
  schemas:
    AnalyzeRequest:
      type: object
      required: [from, to, value, data, context]
      additionalProperties: false
      properties:
        analysisNetwork:
          type: string
          enum: [XLAYER_TESTNET, XLAYER_MAINNET]
          default: XLAYER_TESTNET
        from:
          type: string
          description: Public sender address; may be empty on Testnet.
        to:
          type: string
          pattern: '^0x[0-9a-fA-F]{40}$'
        value:
          type: string
          description: Human OKB decimal, not wei.
        data:
          type: string
          pattern: '^0x(?:[0-9a-fA-F]{2})*$'
        context:
          type: string
          maxLength: 2000
          description: Optional untrusted user intent. The raw value is not included in the Analysis Receipt.
    AnalyzeResponse:
      type: object
      description: Existing V5/V6 analysis fields plus the adjacent deterministic V7 policy decision.
      required: [finalScore, deterministicScore, level, analysisConfidence, analysisVerdict, executionStatus, analysisReceipt, policyDecision]
      properties:
        finalScore: { type: integer, minimum: 0, maximum: 100 }
        deterministicScore: { type: integer, minimum: 0, maximum: 100 }
        aiScore: { type: integer, minimum: 0, maximum: 100 }
        level: { $ref: '#/components/schemas/RiskLevel' }
        analysisConfidence: { type: string, enum: [HIGH, MEDIUM, LOW] }
        analysisVerdict: { type: string, enum: [ASSESSED, UNDETERMINED] }
        executionStatus: { type: string, enum: [SUCCEEDED, REVERTED, UNAVAILABLE] }
        analysisReceipt: { $ref: '#/components/schemas/AnalysisReceipt' }
        analysisAttestation:
          oneOf:
            - { $ref: '#/components/schemas/AnalysisAttestation' }
            - { type: 'null' }
        attestationAvailability: { type: string, enum: [AVAILABLE, UNAVAILABLE, INVALID_CONFIG] }
        policyDecision: { $ref: '#/components/schemas/PolicyDecision' }
      additionalProperties: true
    PolicyDecision:
      type: object
      additionalProperties: false
      required: [policyId, policyVersion, decision, reasonCodes, inputs, aiInfluencedDecision]
      properties:
        policyId: { type: string, const: xguard-pre-sign-policy-v1 }
        policyVersion: { type: string, const: 1.0.0 }
        decision: { type: string, enum: [ALLOW, WARN, REQUIRE_REVIEW, BLOCK_RECOMMENDED] }
        reasonCodes:
          type: array
          minItems: 1
          items:
            type: string
            enum: [DETERMINISTIC_HIGH_RISK, DETERMINISTIC_ELEVATED_RISK, LOW_CONFIDENCE, MEDIUM_CONFIDENCE, VERDICT_UNDETERMINED, EXECUTION_REVERTED, EXECUTION_UNAVAILABLE, INTENT_MISMATCH, INTENT_PARTIAL, EVIDENCE_INCONSISTENT, MAINNET_SIMULATION_UNAVAILABLE, ALLOW_BASELINE]
        inputs:
          type: object
          additionalProperties: false
          required: [deterministicScore, analysisConfidence, analysisVerdict, executionStatus, intentStatus, userIntentPresent, evidenceConsistency, simulationStatus, analysisNetwork]
          properties:
            deterministicScore: { type: integer, minimum: 0, maximum: 100 }
            analysisConfidence: { type: string, enum: [HIGH, MEDIUM, LOW] }
            analysisVerdict: { type: string, enum: [ASSESSED, UNDETERMINED] }
            executionStatus: { type: string, enum: [SUCCEEDED, REVERTED, UNAVAILABLE] }
            intentStatus: { type: string, enum: [MATCH, PARTIAL, MISMATCH, UNKNOWN] }
            userIntentPresent: { type: boolean }
            evidenceConsistency: { type: string, enum: [CONSISTENT, INCONSISTENT, NOT_COMPARABLE] }
            simulationStatus: { type: string, enum: [AVAILABLE, UNAVAILABLE, UNSUPPORTED, ERROR] }
            analysisNetwork: { type: string, enum: [XLAYER_TESTNET, XLAYER_MAINNET] }
        aiInfluencedDecision: { type: boolean, const: false }
    RiskLevel:
      type: string
      enum: [LOW, MEDIUM, HIGH]
    RiskComponent:
      type: object
      required: [score, level]
      additionalProperties: false
      properties:
        score: { type: integer, minimum: 0, maximum: 100 }
        level: { $ref: '#/components/schemas/RiskLevel' }
    AnalysisReceipt:
      type: object
      additionalProperties: false
      required: [receiptType, schemaVersion, analysisId, engine, observedAt, network, transaction, assessment, evidence, provenance, integrity]
      properties:
        receiptType: { type: string, const: xguard.analysis-receipt }
        schemaVersion: { type: string, const: 1.0.0 }
        analysisId: { type: string, format: uuid }
        engine:
          type: object
          additionalProperties: false
          required: [xguardVersion, ruleVersion, decoderVersion]
          properties:
            xguardVersion: { type: string }
            ruleVersion: { type: string }
            decoderVersion: { type: string }
        observedAt: { type: string, format: date-time }
        network:
          type: object
          additionalProperties: false
          required: [analysisNetwork, chainId]
          properties:
            analysisNetwork: { type: string, enum: [XLAYER_TESTNET, XLAYER_MAINNET] }
            chainId: { type: integer, enum: [1952, 196] }
        transaction:
          type: object
          additionalProperties: false
          required: [from, to, value, calldata]
          properties:
            from: { type: [string, 'null'] }
            to: { type: string }
            value: { type: string }
            calldata: { type: string }
        assessment:
          type: object
          additionalProperties: false
          required: [deterministicKnownRisk, aiAdvisory, finalRisk, confidence, verdict, execution, recommendation]
          properties:
            deterministicKnownRisk: { $ref: '#/components/schemas/RiskComponent' }
            aiAdvisory:
              oneOf:
                - { $ref: '#/components/schemas/RiskComponent' }
                - { type: 'null' }
            finalRisk: { $ref: '#/components/schemas/RiskComponent' }
            confidence: { type: string, enum: [HIGH, MEDIUM, LOW] }
            verdict: { type: string, enum: [ASSESSED, UNDETERMINED] }
            execution: { type: string, enum: [SUCCEEDED, REVERTED, UNAVAILABLE] }
            recommendation: { type: string }
        evidence:
          type: object
          additionalProperties: false
          required: [decodedAction, consequences, intentComparison, contractIntelligence, simulationEvidence, evidenceConsistency]
          properties:
            decodedAction: { type: object }
            consequences: { type: array, items: { type: object } }
            intentComparison: { type: object }
            contractIntelligence: { type: object }
            simulationEvidence: { type: object }
            evidenceConsistency: { type: object }
        provenance:
          type: object
          additionalProperties: false
          required: [sources]
          properties:
            sources:
              type: array
              minItems: 4
              maxItems: 4
              items:
                type: object
                additionalProperties: false
                required: [type, provider, status, observedAt, network]
                properties:
                  type: { type: string, enum: [DETERMINISTIC_DECODER, XLAYER_RPC, OKX_ONCHAINOS, AI_ADVISORY] }
                  provider: { type: string }
                  status: { type: string }
                  observedAt: { type: string, format: date-time }
                  network: { type: string, enum: [XLAYER_TESTNET, XLAYER_MAINNET] }
        integrity:
          type: object
          additionalProperties: false
          required: [canonicalizationVersion, hashAlgorithm, fingerprint]
          properties:
            canonicalizationVersion: { type: string, const: xguard-c14n-v1 }
            hashAlgorithm: { type: string, const: SHA-256 }
            fingerprint: { type: string, pattern: '^sha256:[0-9a-f]{64}$' }
    ReceiptBinding:
      type: object
      additionalProperties: false
      required: [receiptType, schemaVersion, analysisId, canonicalizationVersion, hashAlgorithm, fingerprint]
      properties:
        receiptType: { type: string, const: xguard.analysis-receipt }
        schemaVersion: { type: string, const: 1.0.0 }
        analysisId: { type: string, format: uuid }
        canonicalizationVersion: { type: string, const: xguard-c14n-v1 }
        hashAlgorithm: { type: string, const: SHA-256 }
        fingerprint: { type: string, pattern: '^sha256:[0-9a-f]{64}$' }
    AnalysisAttestation:
      type: object
      additionalProperties: false
      required: [attestationType, attestationVersion, algorithm, keyId, signedAt, receiptBinding, publicKeyFingerprint, signature]
      properties:
        attestationType: { type: string, const: xguard.analysis-attestation }
        attestationVersion: { type: string, const: 1.0.0 }
        algorithm: { type: string, const: Ed25519 }
        keyId: { type: string, pattern: '^[a-z0-9._-]{1,64}$' }
        signedAt: { type: string, format: date-time }
        receiptBinding: { $ref: '#/components/schemas/ReceiptBinding' }
        publicKeyFingerprint: { type: string, pattern: '^sha256:[0-9a-f]{64}$' }
        signature: { type: string, pattern: '^[A-Za-z0-9_-]{86}$' }
    AvailableAttestationKey:
      type: object
      additionalProperties: false
      required: [status, keyId, algorithm, publicKeySpkiBase64, publicKeyFingerprint]
      properties:
        status: { type: string, const: AVAILABLE }
        keyId: { type: string, pattern: '^[a-z0-9._-]{1,64}$' }
        algorithm: { type: string, const: Ed25519 }
        publicKeySpkiBase64: { type: string, description: Base64-encoded public SPKI DER bytes only. }
        publicKeyFingerprint: { type: string, pattern: '^sha256:[0-9a-f]{64}$' }
    UnavailableAttestationKey:
      type: object
      additionalProperties: false
      required: [status]
      properties:
        status: { type: string, enum: [UNAVAILABLE, INVALID_CONFIG] }
    AttestationKeyResponse:
      oneOf:
        - { $ref: '#/components/schemas/AvailableAttestationKey' }
        - { $ref: '#/components/schemas/UnavailableAttestationKey' }