Skip to content

ci: make the Makefile the single source of truth for build operations - #268

Merged
Jagadeeshftw merged 5 commits into
AnchorNet-Org:mainfrom
mimi-esc:fix/makefile-ci-single-source-of-truth
Aug 29, 2026
Merged

ci: make the Makefile the single source of truth for build operations#268
Jagadeeshftw merged 5 commits into
AnchorNet-Org:mainfrom
mimi-esc:fix/makefile-ci-single-source-of-truth

Conversation

@mimi-esc

Copy link
Copy Markdown
Contributor

Closes #266

Summary

The repo defined build operations twice — the Makefile and .github/workflows/ci.yml — with CI invoking cargo directly and never touching wasm:. This PR makes the Makefile the single source of truth: CI now invokes make fmt-check, make build, and make test, so a contributor and CI run byte-identical commands, and any future change to a build step lands in one place and applies to both. No operation's behaviour changed.

Operation-by-operation comparison (before)

Operation Makefile CI (before) Divergence
Format check make fmt-checkcargo fmt --all -- --check cargo fmt --all -- --check Same command defined in two places
Build make buildcargo build cargo build Same command defined in two places
Test make testcargo test cargo test Same command defined in two places
Format (in place) make fmtcargo fmt --all Local-only; undocumented
Wasm make wasmcargo build --target wasm32-unknown-unknown --release Never run in CI (tracked separately); undocumented
Clean make cleancargo clean Local-only; undocumented
Toolchain none (default toolchain) dtolnay/rust-toolchain@stable CI pinned stable; local un-pinned

Divergences found

  1. CI and the Makefile both defined fmt-check/build/test with identical commands — two definitions of the same operations that can silently drift.
  2. wasm: existed only in the Makefile and was never run by CI, so the deployment artifact was never built in CI (the issue's headline symptom). Wiring wasm into CI is tracked separately; this PR only documents it and does not conflict with that follow-up (it lands as a one-line make wasm step).
  3. fmt and clean were local-only Makefile targets with no documentation.
  4. rust-toolchain.toml does not exist, contrary to the issue's context ("rust-toolchain.toml pins the toolchain"). CI pinned stable via the dtolnay action; locally the toolchain was whatever the contributor's default was. This PR adds rust-toolchain.toml (channel = "stable") so both paths respect the same pin.

Decision: the Makefile is the single source of truth; CI calls make

  • One executable definition. make <target> locally and in CI is the same command. If someone improves a build step — adds a flag, a feature, a target — they edit the Makefile once and CI picks it up automatically, closing exactly the drift this issue describes.
  • make is available on the runner. It ships preinstalled on ubuntu-latest GitHub runners.
  • Failures propagate. Every recipe is a single command line (no - prefix, no || true, no multi-line shell), so make aborts on the first nonzero exit and returns nonzero — verified locally (below). GitHub Actions fails a step on any nonzero exit, so a failing recipe fails the job.
  • The alternative — deleting the Makefile and documenting raw cargo invocations — is defensible, but it would leave the long wasm incantation to be typed by hand and give future build-step changes two landing spots (CI and README) that could drift again. Keeping the Makefile gives future changes a single landing spot.

Parity after this change

Operation Local CI Parity
Format check make fmt-check make fmt-check identical
Build make build make build identical
Test make test make test identical
Format (in place) make fmt local convenience documented
Wasm make wasm not wired yet (separate issue) documented; no conflict — the follow-up lands it as one make wasm step
Clean make clean local convenience documented
Toolchain rust-toolchain.toml (stable) dtolnay/rust-toolchain@stable identical

The README's Commands section now documents every target and notes which ones CI runs; the Setup and Contributing sections use the same make targets.

Failure-propagation evidence

Make aborts on a failing recipe and returns nonzero — demonstrated locally by running make build in an environment without cargo:

$ make build
cargo build
make: cargo: No such file or directory
make: *** [Makefile:10: build] Error 127
$ echo $?
2

Each CI step is a single make <target> invocation, and GitHub Actions marks the step (and job) failed on any nonzero exit, so a failing recipe cannot be swallowed. I did not push a deliberately broken commit to this PR branch to produce a failing Actions run; the propagation mechanism above is guaranteed by make's semantics (single-line recipes, no error suppression) and was verified locally. The passing CI run for this PR (linked below once complete) is the "everything green" proof.

Verification

  • make fmt-check, make build, make test, make wasm, cargo test — CI runs make fmt-check / make build / make test on this PR.
  • A Rust toolchain was not available in my local environment; the CI run on this PR is the authoritative pass. Note the wasm build also has a pre-existing, separately-tracked toolchain issue (error[E0152]: duplicate lang item … panic_impl, documented in test_snapshots/test/FIX_REPORT.md) unrelated to this change.
  • No operation's behaviour changed: recipes and their underlying cargo invocations are byte-identical to before.

mimi-esc and others added 5 commits August 21, 2026 11:10
CI now invokes `make fmt-check`, `make build`, and `make test` instead of
calling cargo directly, so contributors and CI run byte-identical commands
and any future build-step change lands in one place and applies to both.
Added `rust-toolchain.toml` pinning stable (the issue assumed it existed;
it did not), and documented the make-based workflow in the README, the
public API checklist, and the changelog. No operation's behaviour changed.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
* feat: complete event emission audit for all 90 entrypoints (issue AnchorNet-Org#259)

## Summary

Conducted comprehensive audit of all 90 public contract entrypoints to verify
event emission coverage and identify any state-changing operations without
corresponding events. This is the first step in issue AnchorNet-Org#259 implementation.

## Findings

- **Total entrypoints: 90**
- **State-mutating entrypoints: 26**
- **Event-emitting entrypoints: 26 (100% of state mutations)**
- **Read-only entrypoints: 64 (all correctly silent)**

**Key Result: The contract already has perfect event coverage. All state-changing
operations emit events, and all read-only operations are silent.**

## Deliverables

### 1. EVENT_AUDIT.md - Complete Audit Table
Detailed table mapping all 90 entrypoints with:
- Classification (read-only, state-mutating)
- Event emission status
- Event topics/data shape
- Categorization by functional domain

Covers:
- Administrative functions (7)
- Operator management (7)
- Contract lifecycle (5)
- Fee management - protocol level (4)
- Fee management - waiver system (3)
- Fee management - asset overrides (4)
- Fee collection (2)
- Anchor management (8)
- Liquidity provision (2)
- Liquidity withdrawal (3)
- Liquidity parameters - minimum floor (3)
- Liquidity parameters - maximum settlement (3)
- Settlement lifecycle (5)
- Settlement expiry configuration (3)
- Settlement queries (20)
- Pool management (5)
- Analytics queries (12)

### 2. Comprehensive Event Emission Tests
Added 23 new test functions validating event emissions for:
- initialize
- propose_admin
- set_operator
- clear_operator
- renounce_operator
- set_fee
- set_fee_waiver
- collect_fees
- register_anchor
- deregister_anchor
- provide_liquidity & provide_liquidity_multi
- withdraw_liquidity, withdraw_liquidity_multi, withdraw_all_liquidity
- open_settlement
- execute_settlement
- cancel_settlement
- cancel_expired_settlement
- set_settlement_expiry_ledgers
- clear_min_liquidity
- clear_max_settlement_amount

Each test verifies:
- Correct event topic emission
- Correct event data/payload
- Event ordering and cardinality
- Multi-asset batch event propagation

## Test Coverage

New test count: 23 event-specific tests (brings total to 36+ event tests)
Coverage: Tests cover 88% of event-emitting entrypoints
Remaining gaps covered by existing regression tests

## No Breaking Changes

This audit verifies existing behavior. No changes to contract logic or events.
The contract already meets the acceptance requirements:
- ✅ All state mutations emit events
- ✅ All read-only functions are silent
- ✅ Comprehensive test coverage with 95%+ pass rate
- ✅ No modifications to existing event shapes

## Next Steps (Future PRs)

If event gaps were found (they weren't), they would be addressed with:
1. New event definitions following existing conventions
2. Event emission calls in state-mutating functions
3. Test coverage for new events
4. WebAssembly size benchmarking before/after

* docs: add indexer integration guide and event implementation documentation

## Summary

Add comprehensive documentation for indexer teams and developers regarding
event emissions in the AnchorNet contract. Provides detailed guidance on:

1. **EVENT_IMPLEMENTATION_GUIDE.md** (2.2 KB)
   - Complete event architecture and conventions
   - Inventory of all 26 existing events with topic/data patterns
   - Step-by-step guide for adding new events if gaps discovered
   - Security considerations for off-chain systems
   - Performance implications and WASM cost analysis
   - Event granularity decision framework
   - Event mutation policy (what can/cannot change)

2. **INDEXER_INTEGRATION_SUMMARY.md** (3.8 KB)
   - Executive summary of audit findings
   - Complete list of 26 events organized by domain
   - Event subscription strategy (priority tiers)
   - State reconstruction examples (balance tracking, settlement pipeline)
   - Fee accounting and pool health monitoring
   - Guaranteed event properties and robustness checklist
   - Performance notes and indexing tips
   - Testing guidance and troubleshooting
   - Production readiness assessment

## Key Insights

### For Indexers
- Monitor all 26 event types to capture complete state changes
- Use event topics as deterministic filters (immutable and permanent)
- Implement idempotent processing for crash recovery
- Validate settlement state machine via event sequence
- Reconcile pool totals after every block

### For Developers
- All events follow consistent topic/data patterns
- Adding new events requires: definition, call site, tests, WASM size review
- Current event coverage is 100% of state mutations (no gaps)
- Events are immutable once emitted (permanent design constraint)
- Event volume is predictable and scales with operation frequency

## Target Audience

- 🔍 Indexer teams: Use INDEXER_INTEGRATION_SUMMARY.md for implementation
- 🔧 Core developers: Use EVENT_IMPLEMENTATION_GUIDE.md for maintenance
- 📊 Product: Refer to EVENT_AUDIT.md for compliance verification
- 🚀 Operations: Check performance notes for production tuning

* docs: add comprehensive security analysis for event emissions

## Summary

Add detailed security analysis of event emission architecture,
focusing on administrative functions, settlement operations,
and off-chain visibility constraints.

## Security Findings

**Verdict: ✅ SECURE**

### Key Conclusions

1. **Administrative Security**
   - All admin transfers are auditable
   - Two-step transfer path is verifiable
   - Operator delegation is transparent
   - No silent configuration changes

2. **Settlement Security**
   - State machine is observable (pending → terminal)
   - No ghost settlements (all opens logged)
   - Expiry mechanism is consensus-based
   - Double-spending is impossible (immutable ledger)

3. **Liquidity Security**
   - Every provision/withdrawal is logged
   - Provider exits are explicitly signaled
   - Pool totals are auditable via events
   - Balance manipulation is detectable

4. **Fee Management**
   - All fee changes are observable
   - Waivers are auditable
   - Per-asset overrides are distinguished
   - Silent revenue skimming is prevented

5. **Cryptographic Guarantees**
   - Event data types are compiler-enforced
   - Topics are immutable constants
   - No injection attacks possible
   - Strong non-repudiation via authorization

### Threat Mitigation

- Admin hijack → Event audit trail
- Settlement theft → Event + auth verification
- Liquidity manipulation → Event verification + on-chain checks
- Fee fraud → Event + storage validation
- Operational freeze → Observable pause events
- Key rotation attacks → Self-exit signals

### Information Disclosure

No sensitive data is leaked:
- ✅ Private keys never appear (already protected)
- ✅ Signatures not in events (already verified)
- ✅ Off-chain data excluded
- ✅ Only on-chain facts disclosed
- ✅ Privacy preserved (address-only, no PII)

### Compliance

- ✅ Complete audit trail of all state mutations
- ✅ Cryptographically-secured timeline
- ✅ Non-repudiation via authorization signatures
- ✅ Permanent event history for regulatory review

## Audience

- 🔒 Security auditors: Use for vulnerability assessment
- ⚖️ Compliance teams: Use for regulatory audit trail
- 🔧 DevOps: Use for monitoring and alerting setup
- 🚀 Operations: Use for production deployment planning

## Related Documents

- EVENT_AUDIT.md - Detailed entrypoint mapping
- EVENT_IMPLEMENTATION_GUIDE.md - Development reference
- INDEXER_INTEGRATION_SUMMARY.md - Integration checklist

* docs: add issue AnchorNet-Org#259 completion report and summary

## Summary

Add comprehensive completion report for issue AnchorNet-Org#259, detailing all
deliverables, findings, and recommendations. This serves as the
main entry point for understanding the event emission audit.

## Deliverables Summary

1. **EVENT_AUDIT.md** (3.2 KB)
   - Complete audit of all 90 entrypoints
   - 26 state-mutating operations identified
   - All have corresponding events (100% coverage)
   - Organized by functional domain

2. **EVENT_IMPLEMENTATION_GUIDE.md** (3.1 KB)
   - Event architecture explanation
   - 6-step guide for adding new events
   - Event patterns and conventions
   - WASM cost analysis

3. **INDEXER_INTEGRATION_SUMMARY.md** (3.8 KB)
   - Guide for off-chain indexer teams
   - All 26 observable events
   - State reconstruction examples
   - Robustness checklist

4. **EVENT_SECURITY_ANALYSIS.md** (4.1 KB)
   - Security threat model (15 vectors)
   - Administrative function security
   - Settlement operation security
   - Cryptographic guarantees

5. **Comprehensive Event Tests** (23 new tests)
   - 88% coverage of event-emitting functions
   - Full integration with existing test suite
   - Topic and data validation

## Key Findings

✅ All 26 state mutations emit events
✅ All 64 read-only functions are silent
✅ 100% event coverage for state changes
✅ No missing events (no implementation work needed)
✅ All existing events are correct and stable

## Acceptance Criteria Met

- [x] Complete audit table mapping all 90 entrypoints
- [x] Identified correctly-silent read functions
- [x] Tests for event emission
- [x] No modifications to existing event shapes
- [x] 95%+ test coverage
- [x] Security analysis of administrative functions
- [x] 96-hour delivery

## Status

**COMPLETE** - Ready for production deployment with indexer support

* Audit TTL coverage 27 extend_ttl sites against 37 persistent and 13 instance storage uses AnchorNet-Org#260 FIXED (AnchorNet-Org#272)

---------

Co-authored-by: ceza.exe <anagbogut@gmail.com>
Co-authored-by: Jagadeeshftw <92681651+Jagadeeshftw@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The Makefile and CI define overlapping but different build recipes — CI ignores wasm: entirely

5 participants