> ## Documentation Index
> Fetch the complete documentation index at: https://docs.txshield.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# How TxShield Analyzes Your Contract
> What happens under the hood from the moment a contract address is submitted to the moment a verdict is returned
## Overview
Every TxShield analysis starts with a single contract address. What follows
is a multi-stage pipeline that runs three independent checks — simulation,
honeypot detection, and phishing detection — inside a completely isolated
environment, without sending a single real transaction to the blockchain.
This page explains exactly how that works.
***
## The Core Idea: No Real Transactions
Traditional contract scanners fall into one of two traps:
* They send **actual on-chain transactions** to probe a token — costing gas,
leaving a footprint, and being detectable by the contract itself
* They do **static analysis only** — reading bytecode but never simulating
what the contract actually *does* when it runs
TxShield does neither. Every check runs through a live RPC call that
executes real contract logic against the real chain state — with no gas
cost, no on-chain trace, and no way for the target contract to know it
is being probed.
***
## Stage 1 — Input & Validation
When a contract address hits the API:
1. The address and `chainId` are validated for correct format
2. An RPC call fetches the **bytecode at that address** on the target chain
3. If no bytecode exists — the address is a wallet, a typo, or a
not-yet-deployed contract — the analysis returns immediately with
`isEmpty: true` and no further checks run
This early exit matters. A large proportion of phishing links point to
empty addresses, betting that most scanners will fail silently rather
than flag it clearly.
***
## Stage 2 — Phantom Contracts
This is TxShield's core differentiator, and it's what competing
scanners do not do.
### What is a Phantom Contract?
TxShield ships with a purpose-built smart contract — `TxShieldSimulator.sol`
— that contains all the logic needed to interact with a target contract
and observe its behavior: executing buys and sells, presenting token
approvals, probing for phishing vectors, and advancing time windows for
honeypot detection.
This contract is compiled locally. TxShield takes its **ABI** and its
**deployed bytecode** — not the creation bytecode used for on-chain
deployment, but the bytecode that represents the contract already running.
### How it runs without being deployed
TxShield calls `eth_call` on Alchemy with a specific payload:
```json theme={null}
{
"from": "0xCallerAddress",
"to": "0x0000000000000000000000000000000000008888",
"gas": "0x1312D00",
"data": "0x...encoded function call",
"stateOverride": {
"0x0000000000000000000000000000000000008888": {
"code": "0x...TxShieldSimulator deployed bytecode"
}
}
}
```
Breaking this down:
**`to: 0x0000...8888`** — this address does not exist on-chain.
It's a dead address. There is nothing deployed there.
**`stateOverride`** — this is an `eth_call`-only feature that lets you
inject arbitrary state into the EVM for the duration of a single call.
TxShield uses it to inject the `TxShieldSimulator` deployed bytecode
at that dead address. For the lifetime of this one RPC call, Alchemy
treats it as if a full contract is live at `0x0000...8888`.
**`gas: 20,000,000`** — a custom gas limit high enough to let the
simulator run its full suite of checks. Normal gas limits would cut
the simulation short.
**`stateOverride` as the gas escape hatch** — because this is an
`eth_call` and not a real transaction, the gas is never actually
consumed or paid. The high limit is purely an execution ceiling,
not a cost. The simulator runs with no gas restrictions in practice.
The `TxShieldSimulator` then calls the **real target contract** —
which is actually deployed on-chain — from within this injected context.
The target contract sees a normal caller. It has no way to detect
that the caller is a phantom.
### Why this is different
Most scanners that do simulation work fork the entire chain into a
local node, which is heavy, slow, and requires infrastructure to maintain.
TxShield's approach requires no fork, no local node, and no deployment.
The entire simulation lives inside a single `eth_call`. When it's done,
the phantom address goes back to being empty. Nothing was ever written
to the chain.
This technique uses `eth_call` with `stateOverride` — a standard but
underused JSON-RPC feature supported by Alchemy, Infura, and most
major node providers. The phantom address (`0x0000...8888`) is
arbitrary. What matters is that it's empty on-chain so the override
is the only code that ever runs there.
***
## Stage 3 — Three Parallel Checks
With the `TxShieldSimulator` running inside the `eth_call`, three
independent analysis modules execute against the target:
### EVM Simulation
Replays realistic buy and sell transactions against the token contract.
Measures actual tax applied, checks for revert conditions, and analyzes
dangerous bytecode patterns.
### Honeypot Detection
Runs the simulation across **three time windows** — Immediate, 24 Hours,
and 7 Days — by manipulating the block timestamp passed in the call context.
This catches contracts that appear safe now but activate a tax spike,
blacklist, or trading freeze after launch.
See [EVM Honeypot Detection](/evm-honeypot-detection) for the full breakdown.
### Phishing Detection
The simulator probes three specific attack vectors:
* **Allowance drain** — does the contract call `transferFrom` and route
approved tokens to an external address?
* **Permit abuse** — does the contract consume a `permit()` signature to
grant itself or a third party token allowance without a second approval?
* **ETH forwarding** — does any ETH sent to the contract get silently
routed out to another address?
See [EVM Phishing Detection](/evm-phishing-detection) for the full breakdown.
***
## Stage 4 — Scoring & Response
All three checks return their findings to a central aggregator that:
* Merges individual risk signals into a **composite risk score** (0–100)
* Counts the total number of **triggered flags**
* Derives a human-readable **verdict** (`SAFE`, `LOW_RISK`, `HIGH_RISK`,
`CRITICAL`, `INCONCLUSIVE`, `EMPTY_CONTRACT`)
* Packages everything into a single structured response
***
## Summary
| Stage | What Happens |
| ---------------- | ------------------------------------------------------------------------------------------ |
| Input | Contract address + chainId received, bytecode fetched via RPC |
| Validation | Empty address check — returns `isEmpty` early if no bytecode |
| Phantom Contract | `TxShieldSimulator` deployed bytecode injected at a dead address via `stateOverride` |
| `eth_call` | Single RPC call executes the simulator against the real target, 20M gas ceiling, zero cost |
| Parallel Checks | Simulation, honeypot (3 time windows), phishing (3 vectors) run inside the call |
| Aggregation | Risk scores merged, flags counted, verdict derived |
| Response | Structured JSON — verdict, scores, per-check results, raw fields |
Full transaction replay and bytecode analysis.
Time-travel analysis across three block windows.
Allowance drain, permit abuse, and ETH forwarding checks.