An auditable smart contract release is a chain of evidence, not a green CI badge. The repository should bind the build, threat model, invariant tests, privileged roles, deployment rehearsal, audit scope and handover runbook to one commit.
This guide turns that chain into eight repository checks and a 60-minute technical review. Use it to determine whether a delivery process can reproduce and explain one EVM release. A failed build, unmapped privileged authority or audit report without a scope commit blocks the review.
This is a release-audit framework, not a security certification.
A release claim needs a repository artifact
"Security-first" is not evidence. A threat model and a failing test are evidence. So are a CI result and a deployment manifest.
The Solidity security guidance recommends code review and testing. It also discusses audits, small modular contracts and fail-safe design. A release review should therefore inspect how those practices appear in the repository, not merely ask whether the team uses them.
A neutral rule matters here: Pharos Production's company profile should receive no credit for a claim that cannot be mapped to an inspectable artifact either. Apply the same test to any team presenting the release.
Confidential client work does not invalidate this approach. The delivery team can provide a sanitized repository, a public project, an internal reference implementation or a live screen-share with sensitive names removed. You do not need customer source code. You need proof that the release process exists and can be reproduced.
Freeze one release as the review boundary
Select one recent project close to the target chain and risk model. The review package should identify:
- the exact commit being demonstrated.
- compiler and framework versions, plus the dependency lock.
- reproducible build commands and CI entry points.
- the threat model with declared system invariants.
- every role that can upgrade, pause, mint or administer the system.
- deployment scripts plus a non-production rehearsal record.
- audit scope, remediation changes and unresolved risks.
- the handover runbook with named owners.
Do not request seed phrases, private keys, customer data or proprietary business logic. A good evidence room proves the process without exposing secrets.
An eight-check repository scorecard
Score each check from 0 to 2:
-
0: absent, verbal only or not reproducible. -
1: an artifact exists but is incomplete, stale or not bound to the demonstrated release. -
2: a reviewer can reproduce it and trace it to the same commit, configuration and release scope.
| Check | Evidence to inspect |
0 looks like |
2 looks like |
|---|---|---|---|
| 1. Build provenance | pinned compiler, lockfile, documented commands and CI workflow | "It builds on our lead developer's laptop" | a clean checkout builds with the documented toolchain and no hidden local step |
| 2. Threat model | assets, actors, trust boundaries, external dependencies, abuse cases and invariants | a generic security checklist | named failure scenarios are mapped to controls and tests |
| 3. Test design | unit, fuzz, invariant, integration or fork tests selected for the system's risks | a coverage percentage with no risk mapping | the team can reintroduce a bounded defect and show the relevant test fail |
| 4. Static analysis and review debt | tool configuration, CI output, suppressions, manual-review notes and finding owners | a green badge or tool logo | every material finding is fixed, accepted with rationale or assigned for action |
| 5. Upgrade and admin authority | immutable or proxy decision, role map, current controllers, emergency powers and storage-layout checks | "We use a multisig" with no address or authority map | every privileged action has a controller, change path and observable event |
| 6. Deployment rehearsal | versioned scripts, network parameters, address manifest, verification steps and dry-run receipt | manual console commands reconstructed from memory | the team can replay a non-production deployment from the reviewed commit |
| 7. Audit handoff | scope commit, exclusions, report, remediation pull requests, retest and accepted residual risk | an audit PDF with no repository reference | each finding traces from the reviewed commit to a change and final disposition |
| 8. Operational handover | monitoring, incident roles, pause or containment procedure, key rotation and upgrade runbook | support described only in the proposal | the operator can run the system without an undocumented team-only action |
Across the 8 checks, the maximum is 16, but the total is not the decision. A hard stop overrides the score. Adjust the depth of each check to value at risk. Privilege concentration and external dependencies also matter.
A claim earns points only after it is bound to one release, reproduced and assigned a disposition. Any failed hard gate routes to 0 or BLOCK.
Broader procurement questions such as team scope, regulatory fit, multi-chain experience and engagement evidence belong in a separate blockchain development company evaluation framework. This repository review begins after one delivery system and one release boundary have been selected.
Check the test model, not the test count
Line coverage says which lines executed. It does not say that the important property was asserted.
Ask the team to name the properties that must survive arbitrary user actions. Examples include conservation of assets, bounded issuance, withdrawal availability and authorization of privileged state changes. Then locate those properties in the test suite.
Foundry's invariant-testing documentation explains that invariant campaigns run randomized sequences of calls and assert the declared invariants after each call. The repository should also expose what the fuzzer actually explored. Inspect its targets and run depth, then examine reverts and handler behavior. A passing campaign that never reaches a meaningful state is weak evidence.
One demonstration is especially useful: ask the team to make a reversible local change that violates a declared invariant, then run the relevant test. The point is not theater. It verifies that the test can detect the failure it claims to control.
Read static-analysis suppressions as engineering debt
Static analysis is a gate only when its configuration and output are reviewable. Slither can analyze Solidity and Vyper projects, integrate with CI and emit machine-readable results, as described in the project documentation.
Do not award points for running slither . alone. Inspect excluded detectors and path filters. Then review inline suppressions and the treatment of each material finding. A suppression needs a technical reason and a defined scope. It also needs an owner. Otherwise the tool may be green because the repository taught it not to look.
Required status checks can prevent a protected GitHub branch from accepting changes until configured checks pass. That mechanism is documented in GitHub's protected-branch guidance. During due diligence, confirm that the security job is actually required on the release branch and that its expected source cannot be replaced casually.
Make upgrade authority explicit
"Upgradeable" is not a feature checkbox. It changes the trust model.
For proxy-based systems, request the proxy pattern, initializer logic, storage-layout comparison and the current authority that can change implementation code. OpenZeppelin's upgradeable-contract guidance documents initializer and storage-layout constraints. ERC-1967 defines standard implementation, beacon and optional admin storage slots for common proxy designs.
The evidence room should answer four questions without a sales call:
- Which address can upgrade, pause, mint, seize, recover or change critical parameters?
- What contract, multisig, timelock or governance path controls that address?
- Which event or monitor reveals a change?
- What happens if the controller is compromised or unavailable?
An immutable contract still needs an authority review. The answer may be "no upgrade path," but ownership, external dependencies and emergency behavior must remain visible.
Bind the audit to the release
An audit report describes a scope at a point in time. Record the repository URL and commit hash beside it. Preserve the compiler settings, excluded components and deployed addresses in the same record. Then trace every finding to a remediation pull request, retest result or explicit risk acceptance.
This avoids a common evidence break: the audit covers one commit while the deployment comes from a later branch with unreviewed changes. The team does not need to claim that an audit guarantees safety. It needs to show which code was reviewed and what changed afterward.
The OWASP Smart Contract Security Verification Standard can help structure the threat model and review scope. Its control groups cover architecture and code as well as governance, authorization and external interactions. Treat it as a control reference, not proof that the repository satisfies those controls.
Run a 60-minute technical review
A bounded live session is more discriminating than another capability deck:
| Time | Reviewer asks the delivery team to do | Evidence produced |
|---|---|---|
| 0-10 minutes | check out the named commit and build it with documented commands | reproducible build or a concrete blocker |
| 10-25 minutes | run one unit path and one risk-based fuzz or invariant test | test output plus an explanation of the property being checked |
| 25-40 minutes | walk through roles, upgrade paths and one compromised-admin scenario | privilege map and containment decision |
| 40-50 minutes | trace one audit finding from scope commit to remediation | commit-bound audit trail |
| 50-60 minutes | replay a non-production deployment and inspect the handover package | deployment receipt, address manifest and runbook |
The session is not a coding contest. It tests whether the release evidence remains coherent under inspection.
Hard stops that override the score
Block or pause the release review when any of these remains unresolved:
- a clean checkout cannot build without an undocumented machine or manual step.
- the audit report cannot be tied to a commit and declared scope.
- upgrade, pause, mint or deployment authority cannot be mapped to current controllers.
- a material static-analysis or audit finding is suppressed without rationale and ownership.
- production deployment depends on unrecorded console actions.
- a critical invariant has no test or explicit compensating control.
- the operator cannot monitor or contain the system without undocumented team-only knowledge.
A release can score well on six checks and still fail on unknown upgrade authority. Do not let arithmetic hide a control that can replace the code after review.
Adapt the evidence request to the engagement
During early discovery, finished code may not exist. Review the team's repository template and threat-model method instead. Inspect its CI gates and sample handover package separately. Mark future evidence as a delivery requirement.
For non-EVM work, replace Solidity and Foundry with the target ecosystem's compiler and test framework. Substitute its analyzer and authority model for Slither and ERC-1967. The evidence jobs stay the same.
A small immutable utility contract needs less ceremony than a protocol controlling treasury assets. It does not get a free pass on reproducible builds, authority mapping or release provenance. Scale the depth, not the existence, of the controls.
Send this request before the sales call:
Please prepare a 60-minute technical review tied to one recent, representative release. First, show a sanitized repository or screen-share with a clean build, risk-mapped tests and static-analysis disposition. Then show the privileged-role map, non-production deployment rehearsal, commit-bound audit handoff and operational runbook. Do not share private keys or customer data. Omit confidential business logic as well.
The response shows whether another operator can reproduce the release without undocumented help.
