feat(bb.js): add BBAPI call logging for debugging

[johnathan79717]

Summary

Implements easy capturing of BBAPI calls in bb.js for debugging and replay, as requested in #1581.

Changes

Browser Environment

• Checks localStorage.BBAPI_DEBUG_LOG or URL query parameter BBAPI_DEBUG_LOG
• Automatically downloads captured calls as timestamped msgpack file on API destruction

Node.js Environment

• Checks BBAPI_DEBUG_LOG environment variable for log directory path
• Saves timestamped msgpack files to specified directory

Implementation Details

• Global BBAPI_LOGGING constant initialized by calling shouldLogBbapi() from environment-specific module
• All BBAPI calls automatically logged to global list when BBAPI_LOGGING is true
• Logs flushed automatically in Backend destroy() methods
• Format: size-prefixed (4-byte little-endian) msgpack, compatible with bb msgpack run

Files Added

• barretenberg/ts/src/cbind/browser/bbapi_log.ts - Browser-specific utilities (shouldLogBbapi, saveBbapiLogs)
• barretenberg/ts/src/cbind/node/bbapi_log.ts - Node.js-specific utilities (shouldLogBbapi, saveBbapiLogs)
• barretenberg/ts/src/cbind/bbapi_log_shared.ts - Shared logging infrastructure and global state

Files Modified

• barretenberg/ts/src/cbind/schema_compiler.ts - Integrated logBbapiCall() into generated msgpackCall function, added flushBbapiLogs() to destroy() methods
• barretenberg/ts/src/cbind/README.md - Added comprehensive documentation

Usage

Browser:

// Option 1: localStorage
localStorage.setItem('BBAPI_DEBUG_LOG', 'true');

// Option 2: URL parameter
https://your-app.com/?BBAPI_DEBUG_LOG

Node.js:

export BBAPI_DEBUG_LOG=/tmp/bbapi-logs
node your-app.js

Test Plan

Tested locally with Node.js environment:

• Created mock BBAPI calls
• Verified calls are logged when BBAPI_DEBUG_LOG is set
• Confirmed log file created with correct format (size-prefixed msgpack)
• Verified no logging overhead when disabled

Notes

The implementation follows the exact specification from issue #1581:

• ✅ Browser/node split inside cbind directory
• ✅ shouldLogBbapi() utility in both environments
• ✅ saveBbapiLogs() utility in both environments with size-prefixed msgpack format
• ✅ Global BBAPI_LOGGING variable initialized by calling shouldLogBbapi()
• ✅ Generated code adds to global list when BBAPI_LOGGING is true
• ✅ Logs saved in Backend operations (destroy methods)

Resolves https://github.com/AztecProtocol/barretenberg/issues/1581

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

[johnathan79717]

Testing Complete ✅

Successfully tested the implementation with both logging enabled and disabled.

Test Results

With logging enabled:

BBAPI_DEBUG_LOG=/tmp/bbapi-test node test_bbapi_logging_simple.mjs

✅ Captured 3 BBAPI calls
✅ Created log file: bbapi-logs-2025-11-14T12-37-11-219Z.msgpack (115 bytes)
✅ Log file format verified with parser

Without logging:

node test_bbapi_logging_simple.mjs

✅ 0 calls captured (no overhead when disabled)
✅ No log file created

Parsed log output:

=== Parsing BBAPI Log File ===

Entry #1:
  Size: 29 bytes
  Command: Pedersen Hash
  Data: { "data": { "type": "Buffer", "data": [1, 2, 3] } }

Entry #2:
  Size: 23 bytes
  Command: Blake2s
  Data: { "data": { "type": "Buffer", "data": [4, 5, 6] } }

Entry #3:
  Size: 51 bytes
  Command: CircuitProve
  Data: { "circuit": "test", "witness": { "type": "Buffer", "data": [...] } }

=== Parsed 3 entries ===

---

Test Utilities

Test scripts are available on branch jh/bbapi-call-logging-tests: https://github.com/AztecProtocol/aztec-packages/tree/jh/bbapi-call-logging-tests/barretenberg/ts

• test_bbapi_logging_simple.mjs - Demonstrates BBAPI logging with mock calls
• parse_bbapi_logs.mjs - Parses and displays log files

These can be used for manual testing or as examples for integration tests.

[johnathan79717]

@ludamad Not sure if I understand your spec correctly. Does this match what you had in mind?

[AztecBot]

Flakey Tests

🤖 says: This CI run detected 3 tests that failed, but were tolerated due to a .test_patterns.yml entry.

\033[38;2;188;109;208mFLAKED\033[0m (\033[38;2;250;217;121m8;;http://ci.aztec-labs.com/b7cfe61e38c0ac1db7cfe61e38c0ac1d8;;\033[0m): barretenberg/acir_tests/scripts/browser_prove.sh verify_honk_proof webkit (11s) (code: 1) (\033[38;2;188;109;208mJonathan Hao\033[0m: feat(bb.js): add BBAPI call logging for debugging)
\033[38;2;188;109;208mFLAKED\033[0m (\033[38;2;250;217;121m8;;http://ci.aztec-labs.com/7ff4c874cefda05d7ff4c874cefda05d8;;\033[0m): yarn-project/end-to-end/scripts/run_test.sh simple src/e2e_epochs/epochs_multi_proof.test.ts (171s) (code: 1) group:e2e-p2p-epoch-flakes (\033[38;2;188;109;208mJonathan Hao\033[0m: feat(bb.js): add BBAPI call logging for debugging)
\033[38;2;188;109;208mFLAKED\033[0m (\033[38;2;250;217;121m8;;http://ci.aztec-labs.com/daf1ac1339f234b6daf1ac1339f234b68;;\033[0m): BOX=vite BROWSER=firefox run_compose_test vite-firefox box boxes (433s) (code: 1) (\033[38;2;188;109;208mJonathan Hao\033[0m: feat(bb.js): add BBAPI call logging for debugging)

[ludamad]

LGTM overall! If we can get confirmation it works, and can be replayed with msgpack run, then this looks about right :)

[ludamad]

To test in browser we would likely need to add to the existing yarn-project/ivc-integration/src/browser_chonk_integration.test.ts

[johnathan79717]

✅ Confirmed: Logs can be replayed with bb msgpack run

Successfully tested replay functionality with real BBAPI commands:

Test Commands

Created log file with two real BBAPI calls:

1. Blake2s - Hash data
2. GrumpkinGetRandomFr - Get random field element

Replay Test

$ /path/to/bb msgpack run -i /tmp/bbapi-test/bbapi-logs-*.msgpack

Result: ✅ Both commands executed successfully and returned responses

The log format is correct and fully compatible with bb msgpack run. The binary msgpack output confirms both commands were processed:

• Blake2sResponse with hash value
• GrumpkinGetRandomFrResponse with random fr value

---

Browser test coming up.