Skip to main content
The Base Audit Bot uses dataclasses to represent contracts, audits, tweets, and other entities. All models are defined using Python’s @dataclass decorator.

​
Database Models

These models represent entities stored in the SQLite database.

​
Contract

Represents a deployed smart contract on the Base blockchain.
​
id
Optional[int]
Database primary key. None for new contracts not yet saved.
​
address
str
required
The contract’s Ethereum address (checksummed format).
​
deployer
str
required
Address of the account that deployed the contract.
​
deploy_time
datetime
required
Timestamp when the contract was deployed.
​
tx_hash
str
required
Transaction hash of the contract deployment transaction.
​
repo_url
Optional[str]
GitHub repository URL for the contract’s source code, if available.
​
last_audit
Optional[datetime]
Timestamp of the most recent audit performed on this contract.
​
contract_name
Optional[str]
Name of the contract (e.g., “MyToken”). Defaults to None.
​
is_verified
bool
Whether the contract source code is verified on Basescan. Defaults to False.

​
Audit

Represents an audit result for a specific contract.
​
id
Optional[int]
Database primary key. None for new audits not yet saved.
​
contract_id
int
required
Foreign key reference to the Contract being audited.
​
audit_date
datetime
required
Timestamp when the audit was performed.
​
critical_count
int
required
Number of critical severity findings.
​
high_count
int
required
Number of high severity findings.
​
medium_count
int
required
Number of medium severity findings.
​
low_count
int
required
Number of low severity findings.
​
summary
str
required
Human-readable summary of the audit results.
​
full_report
Optional[str]
Complete audit report in JSON format. Defaults to None.

​
Tweet

Represents a tweet posted by the bot.
​
id
Optional[int]
Database primary key. None for new tweets not yet saved.
​
audit_id
Optional[int]
Foreign key reference to the associated Audit, if applicable.
​
tweet_id
str
required
Twitter’s unique identifier for the posted tweet.
​
posted_at
datetime
required
Timestamp when the tweet was posted.
​
tweet_type
str
required
Type of tweet: 'audit', 'update', or 'summary'.
​
content
str
required
The text content of the tweet.

​
Scanner Models

These models are used by the blockchain scanner.

​
ContractDeployment

Represents a detected contract deployment event from the blockchain.
​
address
str
required
Address of the newly deployed contract.
​
deployer
str
required
Address of the account that deployed the contract.
​
tx_hash
str
required
Transaction hash of the deployment transaction.
​
block_number
int
required
Block number where the contract was deployed.
​
timestamp
datetime
required
Block timestamp of the deployment.
​
bytecode_size
int
required
Size of the contract bytecode in bytes. Used to filter out trivial contracts.

​
Auditor Models

These models represent audit findings and reports generated by the AI auditor.

​
Finding

Represents a single security finding discovered during an audit.
​
severity
str
required
Severity level: "Critical", "High", "Medium", or "Low".
​
title
str
required
Brief title describing the security issue.
​
description
str
required
Detailed explanation of the vulnerability.
​
location
Optional[str]
Function name, line reference, or file where the issue was found. Defaults to None.
​
recommendation
Optional[str]
Suggested fix or mitigation for the vulnerability. Defaults to None.

​
AuditResult

Result of auditing a single Solidity file.
​
file_path
str
required
Path to the audited Solidity file.
​
findings
list[Finding]
List of security findings discovered in this file. Defaults to empty list.
​
error
Optional[str]
Error message if the audit failed. Defaults to None.

​
FullAuditReport

Complete audit report for an entire repository or contract.
​
repo_url
str
required
URL of the audited repository, or "direct_source" for source code audits.
​
audit_date
datetime
required
Timestamp when the audit was performed.
​
files_audited
int
required
Number of Solidity files that were audited.
​
total_findings
int
required
Total count of all findings across all severities.
​
critical_count
int
required
Number of critical severity findings.
​
high_count
int
required
Number of high severity findings.
​
medium_count
int
required
Number of medium severity findings.
​
low_count
int
required
Number of low severity findings.
​
findings
list[Finding]
List of all findings from the audit. Defaults to empty list.
​
summary
str
Human-readable summary of the audit results. Defaults to empty string.
​
error
Optional[str]
Error message if the audit failed. Defaults to None.

​
Usage Examples

​
Creating a Contract

from models import Contract
from datetime import datetime

contract = Contract(
    id=None,
    address="0x1234567890123456789012345678901234567890",
    deployer="0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    deploy_time=datetime.utcnow(),
    tx_hash="0x...",
    repo_url="https://github.com/user/repo",
    last_audit=None,
    contract_name="MyContract",
    is_verified=True
)
```python

### Working with Findings

```python
from auditor import Finding, FullAuditReport
from datetime import datetime

finding = Finding(
    severity="High",
    title="Reentrancy vulnerability",
    description="External call before state update",
    location="withdraw() function",
    recommendation="Use checks-effects-interactions pattern"
)

report = FullAuditReport(
    repo_url="https://github.com/user/contract",
    audit_date=datetime.utcnow(),
    files_audited=5,
    total_findings=1,
    critical_count=0,
    high_count=1,
    medium_count=0,
    low_count=0,
    findings=[finding],
    summary="Found 1 high severity issue"
)
```python

Build docs developers (and LLMs) love

Get started for freeTalk to us