Contract Bytecode Compare API Documentation

POSThttps://www.brainiac.software/api/v1/contract-security/contract-bytecode-compare$0.05 USDC

Compare contract bytecode

Compare two caller-supplied EVM bytecodes. mode exact compares every byte. An omitted mode is exact. mode normalized masks only the supplied immutable ranges and a trailing Solidity CBOR metadata suffix when bytecodeKind is not creation and that suffix is present on both bytecodes. comparison_status is identical, different, partially_comparable, or invalid. Hashes are keccak256 of the supplied bytes. Similarity is the share of equal compared bytes, truncated to 4 decimal places. A difference is not a judgment that either bytecode is malicious, and similar bytecode is not equivalent behavior. No source code is verified and no chain is queried.

Body

Field	Required	Notes
`reference`	Yes	string
`candidate`	Yes	string
`bytecodeKind`	No	string; One of: runtime, creation
`mode`	No	string; One of: exact, normalized
`compilerMetadata`	No	object; Object
`constructorArguments`	No	string
`immutableRanges`	No	array; Array
`expectedDifferences`	No	array; Array

Request exampleJSON

{
  "reference": "0x6001600055aabba2646970667358220000000000000000000000000000000000000000000000000000000000000000000164736f6c63430008180033",
  "candidate": "0x6002600055aabba2646970667358220000000000000000000000000000000000000000000000000000000000000000000264736f6c634300081a0033",
  "bytecodeKind": "runtime",
  "mode": "normalized",
  "compilerMetadata": {
    "compiler": "solc",
    "version": "0.8.24"
  },
  "immutableRanges": [
    {
      "start": 5,
      "end": 7
    }
  ],
  "expectedDifferences": [
    {
      "start": 1,
      "end": 2
    }
  ]
}

Response exampleJSON

{
  "comparison_status": "different",
  "reference_hash": "0xc8a324f6d1a8d63a729defc4c20b624f17d7dae1fdf4b5eec5f7c03a54a8da45",
  "candidate_hash": "0xa39f1cb59ec90edd47f46c666deb79f2aef5e485023e84f1586a677d13ff88a0",
  "reference_length": 60,
  "candidate_length": 60,
  "similarity": "80.0000",
  "difference_ranges": [
    {
      "start": 1,
      "end": 2,
      "length": 1,
      "kind": "changed"
    }
  ],
  "metadata_differences": [
    {
      "field": "metadata",
      "reference": "0xa2646970667358220000000000000000000000000000000000000000000000000000000000000000000164736f6c63430008180033",
      "candidate": "0xa2646970667358220000000000000000000000000000000000000000000000000000000000000000000264736f6c634300081a0033",
      "detail": "The compiler metadata suffixes differ."
    },
    {
      "field": "solc",
      "reference": "0.8.24",
      "candidate": "0.8.26",
      "detail": "The metadata suffixes encode different Solidity versions. This is not a source-code verification."
    },
    {
      "field": "compiler",
      "reference": "0.8.24",
      "candidate": "0.8.26",
      "detail": "compilerMetadata.version is 0.8.24. The suffixes encode 0.8.24 and 0.8.26. This was not checked against source code."
    }
  ],
  "findings": [
    {
      "code": "immutable_ranges_masked",
      "severity": "low",
      "detail": "The supplied immutable ranges were masked before the byte comparison."
    },
    {
      "code": "difference_expected",
      "severity": "low",
      "detail": "The changed bytes at 1:2 fall inside expectedDifferences."
    },
    {
      "code": "bytecode_differs",
      "severity": "medium",
      "detail": "1 unmasked byte ranges differ. A difference is not a judgment that either contract is malicious."
    },
    {
      "code": "metadata_differs",
      "severity": "medium",
      "detail": "The identified compiler metadata differs. This is not a source-code verification."
    },
    {
      "code": "comparison_normalized",
      "severity": "low",
      "detail": "Normalized comparison masked only the supplied immutable ranges and a compiler metadata suffix when that suffix was identified on both bytecodes."
    }
  ],
  "limitations": [
    "Hashes are keccak256 of the supplied bytes before any masking.",
    "Similarity is the share of equal compared bytes, truncated to 4 decimal places with integer division. Masked bytes are left out of the count.",
    "A high similarity does not mean the contracts behave the same way.",
    "A difference is not a judgment that either bytecode is malicious.",
    "No source code was verified. Compiler metadata in the request is not a source match.",
    "Normalization masks only caller-supplied immutable ranges and a trailing compiler metadata suffix when bytecodeKind is not creation and the Solidity CBOR pattern is present on both bytecodes.",
    "Other bytecode is not removed. Creation bytecode is not split into init code and runtime code.",
    "Constructor arguments are checked as a suffix only when bytecodeKind is creation and the arguments are supplied.",
    "No chain state was read, and neither bytecode was executed."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/contract-security/contract-bytecode-compare" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "reference": "0x6001600055aabba2646970667358220000000000000000000000000000000000000000000000000000000000000000000164736f6c63430008180033",
  "candidate": "0x6002600055aabba2646970667358220000000000000000000000000000000000000000000000000000000000000000000264736f6c634300081a0033",
  "bytecodeKind": "runtime",
  "mode": "normalized",
  "compilerMetadata": {
    "compiler": "solc",
    "version": "0.8.24"
  },
  "immutableRanges": [
    {
      "start": 5,
      "end": 7
    }
  ],
  "expectedDifferences": [
    {
      "start": 1,
      "end": 2
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/contract-security/bytecode-structure-diff$0.04 USDC

Diff bytecode structure

Decode two caller-supplied EVM bytecodes, or two instruction lists, into opcodes and compare the instruction sequence. Similarity ignores PUSH immediates. The risk delta counts CALL, SSTORE, CREATE, DELEGATECALL, CALLCODE, and SELFDESTRUCT. A high similarity is not proof that the contracts behave the same. No chain is queried.

Body

Field	Required	Notes
`left`	Yes	—
`right`	Yes	—

Request exampleJSON

{
  "left": "0x6001600055",
  "right": "0x6002600055f4"
}

Response exampleJSON

{
  "similarity_index": 86,
  "risk_delta_score": 71,
  "divergence_points": [
    {
      "index": 0,
      "left": "PUSH1 01",
      "right": "PUSH1 02",
      "kind": "immediate"
    },
    {
      "index": 3,
      "left": "3",
      "right": "4",
      "kind": "length"
    }
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/contract-security/bytecode-structure-diff" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "left": "0x6001600055",
  "right": "0x6002600055f4"
}
JSON