Transaction Intent Verification API Documentation

POSThttps://www.brainiac.software/api/v1/crypto-security/transaction-intent-verify$0.04 USDC

Verify transaction intent

Compare an EVM transaction's calldata and native value with the action declared in the request. Decoding uses the ABI in the request, or the standard ERC-20 transfer, transferFrom, approve, and increaseAllowance encodings when that selector matches. intent_match is true, false, or the string indeterminate when a declared field cannot be checked. risk_level is low, medium, high, or critical. This is static analysis: it does not read chain state, simulate the call, or decide that a contract is malicious or that the transaction will succeed.

Body

Field	Required	Notes
`chainId`	Yes	integer
`contractAddress`	Yes	string
`calldata`	Yes	string
`value`	Yes	string
`expectedAction`	Yes	string; One of: transfer, token_approval, swap, contract_interaction
`expected`	No	object; Object
`abi`	No	array; Array

Request exampleJSON

{
  "chainId": 8453,
  "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "calldata": "0x095ea7b30000000000000000000000002222222222222222222222222222222222222222ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  "value": "0",
  "expectedAction": "token_approval",
  "expected": {
    "spender": "0x2222222222222222222222222222222222222222",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1000000",
    "nativeValue": "0"
  }
}

Response exampleJSON

{
  "intent_match": false,
  "risk_level": "critical",
  "mismatches": [
    {
      "field": "amount",
      "expected": "1000000",
      "actual": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
      "detail": "The approval amount exceeds the expected amount."
    }
  ],
  "decoded_transaction": {
    "selector": "0x095ea7b3",
    "function_name": "approve",
    "parameters": [
      {
        "name": "spender",
        "type": "address",
        "value": "0x2222222222222222222222222222222222222222"
      },
      {
        "name": "amount",
        "type": "uint256",
        "value": "115792089237316195423570985008687907853269984665640564039457584007913129639935"
      }
    ]
  },
  "warnings": [
    {
      "code": "approval_exceeds_expected",
      "detail": "The approval amount is greater than the expected amount."
    },
    {
      "code": "unlimited_approval",
      "detail": "The approval amount is the uint256 maximum. The calldata does not set an expiry."
    }
  ],
  "limitations": [
    "This is static calldata analysis. It does not read chain state, simulate execution, or decide whether the target contract is malicious or whether the transaction will succeed.",
    "Chain ID is not checked against a network and does not change decoding.",
    "The function was decoded with the standard ERC-20 ABI because the selector matched transfer, transferFrom, approve, or increaseAllowance. No caller ABI was supplied."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/crypto-security/transaction-intent-verify" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "chainId": 8453,
  "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "calldata": "0x095ea7b30000000000000000000000002222222222222222222222222222222222222222ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  "value": "0",
  "expectedAction": "token_approval",
  "expected": {
    "spender": "0x2222222222222222222222222222222222222222",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1000000",
    "nativeValue": "0"
  }
}
JSON

POSThttps://www.brainiac.software/api/v1/crypto-security/intent-safety$0.04 USDC

Score transaction intent safety

Read a caller-supplied EVM transaction or an EIP-712 typed-data message and describe the transfer, approval, permit, or outer call it encodes. Known selectors are transfer, transferFrom, approve, increaseAllowance, setApprovalForAll, permit, multicall, aggregate, and execute. The score is a local penalty count. It does not simulate the call or read a chain.

Body

Field	Required	Notes
`transaction`	No	object; Object
`typed_data`	No	object; Object

Request exampleJSON

{
  "transaction": {
    "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "value": "0",
    "data": "0x095ea7b30000000000000000000000002222222222222222222222222222222222222222ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
  }
}

Response exampleJSON

{
  "intent_safety_score": 55,
  "unintended_transfers_risk": 55,
  "human_readable_intent": "Approve 0x2222222222222222222222222222222222222222 to spend the maximum uint256 of the token at 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913. The approval has no deadline in the calldata."
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/crypto-security/intent-safety" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "transaction": {
    "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "value": "0",
    "data": "0x095ea7b30000000000000000000000002222222222222222222222222222222222222222ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
  }
}
JSON

POSThttps://www.brainiac.software/api/v1/crypto-security/proxy-upgrade-storage-audit$0.05 USDC

Audit proxy upgrade storage

Compare the Solidity storage layout of an upgradeable implementation with a proposed replacement. Variables are matched by slot and offset, not by name. The types map is used for structs, mappings, dynamic arrays, and byte sizes. compatibility_status is compatible, incompatible, warnings, or indeterminate. risk_level is low, medium, high, or critical. A compatible result is not a claim that the upgrade is safe. No chain is queried.

Body

Field	Required	Notes
`proxyPattern`	No	string; One of: uups, transparent, beacon, custom
`current`	Yes	object; Object
`proposed`	Yes	object; Object
`currentMetadata`	No	object; Object
`proposedMetadata`	No	object; Object

Request exampleJSON

{
  "proxyPattern": "uups",
  "currentMetadata": {
    "contractName": "Box",
    "compilerVersion": "0.8.24+commit.e11b9ed9"
  },
  "proposedMetadata": {
    "contractName": "BoxV2",
    "compilerVersion": "0.8.26+commit.8a97fa7a"
  },
  "current": {
    "storage": [
      {
        "label": "value",
        "offset": 0,
        "slot": "0",
        "type": "t_uint256",
        "contract": "Box.sol:Box"
      },
      {
        "label": "owner",
        "offset": 0,
        "slot": "1",
        "type": "t_address",
        "contract": "Box.sol:Box"
      },
      {
        "label": "__gap",
        "offset": 0,
        "slot": "2",
        "type": "t_array(t_uint256)50_storage",
        "contract": "Box.sol:Box"
      }
    ],
    "types": {
      "t_uint256": {
        "encoding": "inplace",
        "label": "uint256",
        "numberOfBytes": "32"
      },
      "t_uint128": {
        "encoding": "inplace",
        "label": "uint128",
        "numberOfBytes": "16"
      },
      "t_address": {
        "encoding": "inplace",
        "label": "address",
        "numberOfBytes": "20"
      },
      "t_array(t_uint256)50_storage": {
        "encoding": "inplace",
        "label": "uint256[50]",
        "numberOfBytes": "1600",
        "base": "t_uint256"
      },
      "t_array(t_uint256)49_storage": {
        "encoding": "inplace",
        "label": "uint256[49]",
        "numberOfBytes": "1568",
        "base": "t_uint256"
      }
    }
  },
  "proposed": {
    "storage": [
      {
        "label": "value",
        "offset": 0,
        "slot": "0",
        "type": "t_uint256",
        "contract": "BoxV2.sol:BoxV2"
      },
      {
        "label": "owner",
        "offset": 0,
        "slot": "1",
        "type": "t_uint256",
        "contract": "BoxV2.sol:BoxV2"
      },
      {
        "label": "extra",
        "offset": 16,
        "slot": "1",
        "type": "t_uint128",
        "contract": "BoxV2.sol:BoxV2"
      },
      {
        "label": "__gap",
        "offset": 0,
        "slot": "2",
        "type": "t_array(t_uint256)49_storage",
        "contract": "BoxV2.sol:BoxV2"
      }
    ],
    "types": {
      "t_uint256": {
        "encoding": "inplace",
        "label": "uint256",
        "numberOfBytes": "32"
      },
      "t_uint128": {
        "encoding": "inplace",
        "label": "uint128",
        "numberOfBytes": "16"
      },
      "t_address": {
        "encoding": "inplace",
        "label": "address",
        "numberOfBytes": "20"
      },
      "t_array(t_uint256)50_storage": {
        "encoding": "inplace",
        "label": "uint256[50]",
        "numberOfBytes": "1600",
        "base": "t_uint256"
      },
      "t_array(t_uint256)49_storage": {
        "encoding": "inplace",
        "label": "uint256[49]",
        "numberOfBytes": "1568",
        "base": "t_uint256"
      }
    }
  }
}

Response exampleJSON

{
  "compatibility_status": "incompatible",
  "risk_level": "critical",
  "storage_differences": [
    {
      "code": "slot_collision",
      "severity": "critical",
      "slot": "1",
      "offset": 0,
      "variable": "owner",
      "detail": "The proposed layout overlaps owner and extra at slot 1."
    },
    {
      "code": "type_changed",
      "severity": "critical",
      "slot": "1",
      "offset": 0,
      "variable": "owner",
      "detail": "Slot 1 offset 0 changed from owner (address) to owner (uint256)."
    },
    {
      "code": "inserted",
      "severity": "high",
      "slot": "1",
      "offset": 16,
      "variable": "extra",
      "detail": "extra at slot 1 offset 16 is not in the current layout and is not an append after its last byte."
    },
    {
      "code": "gap_modified",
      "severity": "critical",
      "slot": "2",
      "offset": 0,
      "variable": "__gap",
      "detail": "Gap __gap at slot 2 occupies 50 slots. The proposed layout does not fill that region with new variables followed by the remaining gap."
    },
    {
      "code": "compiler_version_differs",
      "severity": "medium",
      "detail": "The layouts name compiler 0.8.24 and 0.8.26. The comparison uses only the supplied layouts."
    },
    {
      "code": "inheritance_order_changed",
      "severity": "medium",
      "detail": "The declaring contracts in slot order changed from Box.sol:Box to BoxV2.sol:BoxV2."
    }
  ],
  "affected_variables": [
    {
      "label": "owner",
      "slot": "1",
      "offset": 0,
      "change": "slot_collision"
    },
    {
      "label": "owner",
      "slot": "1",
      "offset": 0,
      "change": "type_changed"
    },
    {
      "label": "extra",
      "slot": "1",
      "offset": 16,
      "change": "inserted"
    },
    {
      "label": "__gap",
      "slot": "2",
      "offset": 0,
      "change": "gap_modified"
    }
  ],
  "slot_collisions": [
    {
      "slot": "1",
      "offset": 0,
      "variables": [
        "owner",
        "extra"
      ],
      "detail": "The proposed layout overlaps owner and extra at slot 1."
    }
  ],
  "type_changes": [
    {
      "label": "owner",
      "slot": "1",
      "offset": 0,
      "previous_type": "address",
      "proposed_type": "uint256",
      "detail": "Slot 1 offset 0 changed from owner (address) to owner (uint256)."
    }
  ],
  "recommendations": [
    "This comparison is structural. It does not execute the contracts or prove that an upgrade is safe.",
    "Do not upgrade until every incompatible storage difference is resolved.",
    "Keep the same type at each occupied slot and offset.",
    "Change a storage gap only by placing new variables in its freed slots and leaving the remaining gap directly after them.",
    "Remove overlapping variables so each byte of a slot belongs to one variable.",
    "Recompile both implementations with the same compiler and compare those layouts."
  ],
  "limitations": [
    "Only the storage layouts in this request were compared. No bytecode, proxy address, or chain state was read.",
    "Variables are matched by slot and offset. A matching name is not storage identity.",
    "A compatible result means no structural difference was found in the supplied layouts. It does not prove that an upgrade is safe or that runtime behavior is unchanged.",
    "Struct, mapping, and dynamic-array layouts are read only from the supplied types map. Missing type entries are not inferred.",
    "Elementary widths are taken from compiler type ids such as t_uint256, or from numberOfBytes when the types map includes it.",
    "A __gap length is read from numberOfBytes or from a uint256[N] compiler type id. Other array lengths are not inferred.",
    "The contract field is compared as supplied. It is not resolved to a source file.",
    "Compiler versions are labels from the request. Different versions are not given different packing rules.",
    "The proxy pattern is uups. This compares implementation layouts only. ERC-1967 proxy slots were not added."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/crypto-security/proxy-upgrade-storage-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "proxyPattern": "uups",
  "currentMetadata": {
    "contractName": "Box",
    "compilerVersion": "0.8.24+commit.e11b9ed9"
  },
  "proposedMetadata": {
    "contractName": "BoxV2",
    "compilerVersion": "0.8.26+commit.8a97fa7a"
  },
  "current": {
    "storage": [
      {
        "label": "value",
        "offset": 0,
        "slot": "0",
        "type": "t_uint256",
        "contract": "Box.sol:Box"
      },
      {
        "label": "owner",
        "offset": 0,
        "slot": "1",
        "type": "t_address",
        "contract": "Box.sol:Box"
      },
      {
        "label": "__gap",
        "offset": 0,
        "slot": "2",
        "type": "t_array(t_uint256)50_storage",
        "contract": "Box.sol:Box"
      }
    ],
    "types": {
      "t_uint256": {
        "encoding": "inplace",
        "label": "uint256",
        "numberOfBytes": "32"
      },
      "t_uint128": {
        "encoding": "inplace",
        "label": "uint128",
        "numberOfBytes": "16"
      },
      "t_address": {
        "encoding": "inplace",
        "label": "address",
        "numberOfBytes": "20"
      },
      "t_array(t_uint256)50_storage": {
        "encoding": "inplace",
        "label": "uint256[50]",
        "numberOfBytes": "1600",
        "base": "t_uint256"
      },
      "t_array(t_uint256)49_storage": {
        "encoding": "inplace",
        "label": "uint256[49]",
        "numberOfBytes": "1568",
        "base": "t_uint256"
      }
    }
  },
  "proposed": {
    "storage": [
      {
        "label": "value",
        "offset": 0,
        "slot": "0",
        "type": "t_uint256",
        "contract": "BoxV2.sol:BoxV2"
      },
      {
        "label": "owner",
        "offset": 0,
        "slot": "1",
        "type": "t_uint256",
        "contract": "BoxV2.sol:BoxV2"
      },
      {
        "label": "extra",
        "offset": 16,
        "slot": "1",
        "type": "t_uint128",
        "contract": "BoxV2.sol:BoxV2"
      },
      {
        "label": "__gap",
        "offset": 0,
        "slot": "2",
        "type": "t_array(t_uint256)49_storage",
        "contract": "BoxV2.sol:BoxV2"
      }
    ],
    "types": {
      "t_uint256": {
        "encoding": "inplace",
        "label": "uint256",
        "numberOfBytes": "32"
      },
      "t_uint128": {
        "encoding": "inplace",
        "label": "uint128",
        "numberOfBytes": "16"
      },
      "t_address": {
        "encoding": "inplace",
        "label": "address",
        "numberOfBytes": "20"
      },
      "t_array(t_uint256)50_storage": {
        "encoding": "inplace",
        "label": "uint256[50]",
        "numberOfBytes": "1600",
        "base": "t_uint256"
      },
      "t_array(t_uint256)49_storage": {
        "encoding": "inplace",
        "label": "uint256[49]",
        "numberOfBytes": "1568",
        "base": "t_uint256"
      }
    }
  }
}
JSON

POSThttps://www.brainiac.software/api/v1/crypto-security/storage-slot-grade$0.04 USDC

Grade proxy storage slot changes

Compare two caller-supplied storage layouts by slot, offset, and size. A name that moves is a shift. Different names that occupy the same bytes are a collision. The grade and the collision score come from those counts. A variable is one slice of a single slot. No chain is queried.

Body

Field	Required	Notes
`previous`	Yes	array; Array
`next`	Yes	array; Array

Request exampleJSON

{
  "previous": [
    {
      "name": "value",
      "slot": 0,
      "offset": 0,
      "size": 32
    },
    {
      "name": "owner",
      "slot": 1,
      "offset": 0,
      "size": 20
    }
  ],
  "next": [
    {
      "name": "value",
      "slot": 0,
      "offset": 0,
      "size": 32
    },
    {
      "name": "extra",
      "slot": 1,
      "offset": 0,
      "size": 32
    },
    {
      "name": "owner",
      "slot": 2,
      "offset": 0,
      "size": 20
    }
  ]
}

Response exampleJSON

{
  "upgrade_safety_grade": "F",
  "collision_probability_score": 55,
  "slot_shift_delta": [
    {
      "name": "owner",
      "from_slot": 1,
      "to_slot": 2,
      "from_offset": 0,
      "to_offset": 0
    }
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/crypto-security/storage-slot-grade" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "previous": [
    {
      "name": "value",
      "slot": 0,
      "offset": 0,
      "size": 32
    },
    {
      "name": "owner",
      "slot": 1,
      "offset": 0,
      "size": 20
    }
  ],
  "next": [
    {
      "name": "value",
      "slot": 0,
      "offset": 0,
      "size": 32
    },
    {
      "name": "extra",
      "slot": 1,
      "offset": 0,
      "size": 32
    },
    {
      "name": "owner",
      "slot": 2,
      "offset": 0,
      "size": 20
    }
  ]
}
JSON