PreparedTx

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gulltoppr-dev/json-schema/gulltoppr-dev-prepared-tx-schema.json",
  "title": "PreparedTx",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gulltoppr-dev-openapi.json#/components/schemas/PreparedTx",
  "type": "object",
  "required": [
    "unsigned_tx",
    "simulation",
    "human_summary",
    "deeplink",
    "warnings",
    "safety"
  ],
  "properties": {
    "unsigned_tx": {
      "$ref": "#/$defs/UnsignedTx"
    },
    "simulation": {
      "$ref": "#/$defs/Simulation"
    },
    "human_summary": {
      "type": "string"
    },
    "deeplink": {
      "type": "string",
      "description": "Configured signing URL. Empty when safety.signing_recommended is false."
    },
    "wallet_request": {
      "$ref": "#/$defs/WalletRequest",
      "description": "EIP-1193-shaped request for wallet/app integrations. Omitted when safety.signing_recommended is false."
    },
    "warnings": {
      "type": "array",
      "description": "Human-readable warnings an agent must show before presenting any signing hand-off.",
      "items": {
        "type": "string"
      }
    },
    "safety": {
      "$ref": "#/$defs/PreparedTxSafety"
    }
  },
  "$defs": {
    "Address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$"
    },
    "AssetChange": {
      "type": "object",
      "required": [
        "address",
        "token",
        "delta",
        "kind"
      ],
      "properties": {
        "address": {
          "$ref": "#/$defs/Address"
        },
        "token": {
          "$ref": "#/$defs/Address"
        },
        "symbol": {
          "type": "string"
        },
        "delta": {
          "$ref": "#/$defs/SignedDecimal"
        },
        "kind": {
          "type": "string",
          "enum": [
            "erc20",
            "erc721",
            "erc1155",
            "native"
          ]
        }
      }
    },
    "Calldata": {
      "type": "string",
      "pattern": "^0x([0-9a-fA-F]{2})*$"
    },
    "DecimalWei": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Native value in wei, decimal string."
    },
    "Hex": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]*$"
    },
    "PreparedTxSafety": {
      "type": "object",
      "required": [
        "signing_recommended",
        "risk_level",
        "requires_human_confirmation",
        "reasons"
      ],
      "properties": {
        "signing_recommended": {
          "type": "boolean",
          "description": "True only when the simulation succeeded and the hand-off may be presented to the user."
        },
        "risk_level": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "blocked"
          ],
          "description": "blocked means do not send; high means require explicit human confirmation before presenting any hand-off."
        },
        "requires_human_confirmation": {
          "type": "boolean",
          "description": "True when provenance, proxy, value, approval, or asset-outflow risks must be shown and confirmed by the user."
        },
        "reasons": {
          "type": "array",
          "description": "Machine-readable warnings an agent must surface before any signing hand-off.",
          "items": {
            "type": "string",
            "enum": [
              "abi_names_inferred",
              "proxy",
              "simulation_failed",
              "native_value",
              "spending_approval",
              "asset_outflow"
            ]
          }
        }
      }
    },
    "SignedDecimal": {
      "type": "string",
      "pattern": "^-?\\d+$",
      "description": "Signed decimal integer string."
    },
    "SimLog": {
      "type": "object",
      "required": [
        "address"
      ],
      "properties": {
        "address": {
          "$ref": "#/$defs/Address"
        },
        "event": {
          "type": "string"
        },
        "args": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "Simulation": {
      "type": "object",
      "required": [
        "success",
        "gas_used",
        "state_diff",
        "asset_changes",
        "logs"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "gas_used": {
          "type": "integer",
          "minimum": 0
        },
        "return_value": {
          "type": "object",
          "required": [
            "decoded",
            "raw"
          ],
          "properties": {
            "decoded": {
              "type": "array",
              "items": true
            },
            "raw": {
              "$ref": "#/$defs/Calldata"
            }
          }
        },
        "state_diff": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/StateDiffEntry"
          }
        },
        "asset_changes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AssetChange"
          }
        },
        "logs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SimLog"
          }
        },
        "revert": {
          "type": "object",
          "required": [
            "reason"
          ],
          "properties": {
            "reason": {
              "type": "string"
            },
            "decoded": {
              "type": "string"
            }
          }
        }
      }
    },
    "StateDiffEntry": {
      "type": "object",
      "required": [
        "address",
        "before",
        "after"
      ],
      "properties": {
        "address": {
          "$ref": "#/$defs/Address"
        },
        "slot_label": {
          "type": "string"
        },
        "before": {
          "type": "string"
        },
        "after": {
          "type": "string"
        }
      }
    },
    "UnsignedTx": {
      "type": "object",
      "required": [
        "chainId",
        "to",
        "from",
        "data",
        "value"
      ],
      "properties": {
        "chainId": {
          "type": "integer"
        },
        "to": {
          "$ref": "#/$defs/Address"
        },
        "from": {
          "$ref": "#/$defs/Address"
        },
        "data": {
          "$ref": "#/$defs/Calldata"
        },
        "value": {
          "$ref": "#/$defs/DecimalWei"
        },
        "gas": {
          "$ref": "#/$defs/DecimalWei"
        }
      }
    },
    "WalletRequest": {
      "type": "object",
      "required": [
        "chainId",
        "method",
        "params"
      ],
      "properties": {
        "chainId": {
          "type": "integer",
          "description": "Routing metadata; switch the wallet to this chain before requesting signature."
        },
        "method": {
          "type": "string",
          "enum": [
            "eth_sendTransaction"
          ]
        },
        "params": {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "$ref": "#/$defs/WalletTransactionRequest"
          }
        }
      }
    },
    "WalletTransactionRequest": {
      "type": "object",
      "required": [
        "from",
        "to",
        "data",
        "value"
      ],
      "properties": {
        "from": {
          "$ref": "#/$defs/Address"
        },
        "to": {
          "$ref": "#/$defs/Address"
        },
        "data": {
          "$ref": "#/$defs/Calldata"
        },
        "value": {
          "$ref": "#/$defs/Hex",
          "description": "JSON-RPC quantity hex."
        },
        "gas": {
          "$ref": "#/$defs/Hex",
          "description": "JSON-RPC quantity hex."
        }
      }
    }
  }
}