SECTION_09

The Proactive Audit Habit

Build better apps by making regular self-audits part of your workflow.

[The Counterintuitive Truth]

The builds that look cleanest on the surface often have the most hidden issues. A polished UI can mask broken error states, insecure data access, and mobile layouts that only fail on specific screen sizes. Always audit.

> Why Audit Even Perfect Builds?

Caffeine's audit agents look at your app from angles you don't naturally consider when building:

🔐

Security gaps you didn't think of

Canister methods callable without authentication. User A reading User B's data.

📱

Mobile failures at specific viewports

Layouts that look fine in browser devtools but break on real phones.

⚡

Edge cases in async flows

What happens if the canister call times out mid-operation? What if it fails silently?

♿

Accessibility issues

Missing ARIA labels, keyboard traps, invisible focus states.

🔄

Upgrade safety problems

Mutable state that breaks on canister upgrade. Missing stable var declarations.

[ICP DATA SAFETY]

Even if an audit reveals issues requiring a redeployment, ICP's architecture ensures your stable variables and canister state are never lost during upgrades. This makes iterative auditing and fixing a safe, low-risk habit — not a scary operation.

> The Proactive Audit Prompt

Run after every major build

The build looks good on the surface. Run a deep audit anyway.

Focus on:
- Edge cases that would fail in production
- Security gaps in canister access control
- Authentication flow problems (Internet Identity cancellation, timeout, re-login)
- Mobile layout issues on real device sizes
- Error states that aren't handled gracefully
- Data integrity under concurrent updates
- Canister upgrade safety (stable vars, migration)

Report everything you find, even minor issues.

> NATIONOS CASE STUDY — UPGRADE-SAFE BY DESIGN

NationOS is an on-chain governance system managing real voting records, treasury transactions, constitutional amendments, and dual-token economics — all living inside ICP canisters.

The risk: during a canister upgrade, every non-stable variable is wiped completely. Losing governance history, voting tallies, or financial records in a live governance system isn't a bug — it's a catastrophic failure of trust.

⚠ The Problem

Canister upgrades erase all non-stable state. Governance votes, treasury balances, constitutional records — gone instantly if not declared as stable.

✓ The Solution

Every critical data store uses stable var in Motoko — governance records, financial transactions, voting history, and constitutional amendments.

Result

NationOS can be upgraded, patched, and improved without losing a single governance record or financial entry. Upgrades become safe, routine operations — not crisis-level deployments.

Key Prompt Habit

Always add to your audit prompt: Verify all critical data uses stable storage. Non-stable vars will be lost on upgrade.

Copyable — Upgrade Safety Audit Prompt

Audit this canister for upgrade safety. Check that all user data, financial records, and state that must survive upgrades is declared as stable var. List every variable that is NOT stable and would be wiped on upgrade. Flag any data that should be migrated to stable storage before the next deployment.

> Domain-Specific Audits

DeFi / token audit

Run a DeFi-specific security audit. Focus on:
- Token decimal handling (are we displaying correctly?)
- Integer overflow in balance calculations
- Reentrancy risks in transfer flows
- Authorization on all balance-modifying methods
- ICRC-1 compliance of all token operations

Social app audit

Run a privacy and social audit. Focus on:
- Can users access other users' private data?
- Are usernames and profiles properly scoped?
- Content moderation edge cases
- Profile deletion data cleanup
- Rate limiting on write operations

// Proactive Audit Habit

Audit after every major feature addition — not just at the end
Use domain-specific audit prompts for DeFi, social, etc.
Never skip the audit because 'it looks fine'
Apply all critical and warning fixes before shipping
Re-audit after major fixes are applied