feat: logger-agnostic logging system

[micbakos]

Summary

Adds a pluggable, logger-agnostic logging system to the SDK. Internal console.debug/console.warn calls are replaced with a level-gated logger that is silent by default and only active when the client opts in.

Usage

The SDK accepts any object with debug, info, warn, and error methods — console works out of the box, as do libraries like pino, winston, and react-native-logs (no adapters needed).

import { StarkZap } from "starkzap";

// Quick debugging with console
const sdk = new StarkZap({
  network: "mainnet",
  logging: { logger: console },
});

// Production with pino, filtering to warn+
import pino from "pino";
const sdk = new StarkZap({
  network: "mainnet",
  logging: { logger: pino(), logLevel: "warn" },
});

When logging is omitted the SDK produces zero output. When provided without logLevel, all severity levels are forwarded to the logger.

The web example's Activity Log now includes an opt-in "Show SDK traces" checkbox that pipes all SDK log output into the UI.

Made with Cursor

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• New Features
  • Introduced configurable SDK logging with adjustable severity levels for improved diagnostics and troubleshooting
  • SDK debug traces now appear in the Activity Log with an optional visibility toggle
  • Enhanced logging throughout bridge operations and transaction monitoring for better error tracking

Walkthrough

This PR introduces a comprehensive logging system to the StarkZap SDK. A new logger module exports Logger, LoggerConfig, and StarkZapLogger classes, supporting level-based filtering and lazy message evaluation. Logging is integrated throughout the bridge ecosystem (operators, monitors, fee handlers), with logger parameters added to constructors and console.* calls replaced with logger calls. The web UI gains an SDK traces toggle. Configuration types and wallet/SDK initialization now support optional logging config propagation.

Changes

Cohort / File(s)	Summary
Logger Infrastructure src/logger/index.ts, tests/logger.test.ts	New logging module with Logger, LogLevel, LoggerConfig, StarkZapLogger class, NOOP_LOGGER singleton, and createLogger factory. Comprehensive test coverage for severity gating, lazy message resolution, and method routing.
Web UI examples/web/index.html, examples/web/main.ts	Added CSS for muted SDK log styling and layout classes for activity log header. Introduced checkbox toggle to show/hide SDK traces with state management and DOM manipulation.
SDK Core Integration src/sdk.ts, src/index.ts, src/types/config.ts	Extended StarkZap config shape and resolved config to include optional logging?: LoggerConfig. Added public type exports for logger types. Wired logger creation in token repository initialization.
Wallet Initialization src/wallet/base.ts, src/wallet/cartridge.ts, src/wallet/index.ts	Added logging option to wallet constructor chains and created logger instances in BaseWallet. Logger propagated from SDKConfig through Wallet to BaseWallet to BridgeOperator.
Bridge Operator src/bridge/operator/BridgeOperator.ts	Updated constructor to accept logger parameter. Injects logger into all bridge implementations (LordsBridge, CanonicalEthereumBridge, OftBridge, CCTPBridge) and all monitor instances (SolanaHyperlaneMonitor, CanonicalMonitor, CctpMonitor, OftMonitor).
Ethereum Bridge Classes src/bridge/ethereum/EthereumBridge.ts, src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts, src/bridge/ethereum/lords/LordsBridge.ts, src/bridge/ethereum/oft/OftBridge.ts	Added logger parameter to constructors and forwarded to parent classes. Replaced console.debug(...) error logging in CanonicalEthereumBridge catch blocks with this.logger.debug(...).
CCTP Bridge & Fees src/bridge/ethereum/cctp/CCTPBridge.ts, src/bridge/ethereum/cctp/CCTPFees.ts	Converted CCTPFees from singleton pattern to dependency-injected logger-aware class. Updated CCTPBridge with explicit constructor accepting logger and CCTPFees instance. Replaced console.error/debug with logger calls.
Bridge Monitoring src/bridge/monitor/utils.ts, src/bridge/monitor/cctp/CctpMonitor.ts, src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts, src/bridge/monitor/oft/OftMonitor.ts, src/bridge/monitor/canonical/CanonicalMonitor.ts	Added optional logger parameter to checkStarknetTxStatus. Updated all monitor options interfaces to require logger property. Replaced console.debug(...) calls with this.logger.debug(...) in exception handlers.
Token & Utilities src/bridge/tokens/repository.ts, src/erc20/token/index.ts	Added optional logger parameter to BridgeTokenRepository and token resolution functions. Replaced console.warn(...) with logger?.warn(...) for dependency and parsing errors.
Package Native SDK packages/native/src/sdk.ts, packages/native/src/wallet/cartridge.ts	Extended StarkZap.connectCartridge to pass logging config to NativeCartridgeWallet.create. Updated NativeCartridgeWalletOptions to accept optional logging?: LoggerConfig.
Export & API src/bridge/index.ts	Removed barrel re-exports for @/bridge/tokens/repository and @/bridge/operator to avoid circular dependencies and control API surface.
Tests tests/bridge-token-repository.test.ts	Updated test imports and added createMockLogger helper. Updated token skipping tests to verify logger warnings instead of console.warn calls.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• PR #115: Directly extends withdrawal/monitoring code by adding logging integration to checkStarknetTxStatus, monitor classes, and related handlers.
• PR #105: Modifies the same bridge/token subsystems (CCTPFees, bridge token repository) with overlapping class changes.
• PR #55: Modifies BaseWallet constructor signatures and initialization patterns that are extended here for logging.

Suggested reviewers

• ZackAttax
• 0xLucqs

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main feature: a pluggable, logger-agnostic logging system with level gating, matching the core changeset across multiple files.
Description check	✅ Passed	The description clearly explains the logging system's purpose, usage patterns, and configuration options, directly related to the changeset's implementation of logger integration throughout the SDK.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch logger

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 7

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/bridge/ethereum/EthereumBridge.ts (1)

58-63: ⚠️ Potential issue | 🟠 Major

Constructor parameter order introduces a backward-compatibility break.

At Line 62, logger was inserted before bridgeAbi (Line 63). Existing positional callers that passed a custom ABI as the 4th argument will now be misinterpreted.

Proposed compatibility-safe adjustment

   constructor(
     protected readonly bridgeToken: EthereumBridgeToken,
     protected readonly config: EthereumWalletConfig,
     readonly starknetWallet: WalletInterface,
-    protected readonly logger: StarkZapLogger = NOOP_LOGGER,
-    bridgeAbi: InterfaceAbi = CANONICAL_BRIDGE_ABI
+    bridgeAbi: InterfaceAbi = CANONICAL_BRIDGE_ABI,
+    protected readonly logger: StarkZapLogger = NOOP_LOGGER
   ) {

As per coding guidelines, for src/** this is a public SDK and changes must prioritize backwards compatibility and clear typed APIs.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/bridge/ethereum/EthereumBridge.ts` around lines 58 - 63, The constructor
parameter order change breaks positional callers: move the bridgeAbi parameter
back to the 4th position and keep logger as the 5th to restore backward
compatibility (i.e., signature should be constructor(protected readonly
bridgeToken: EthereumBridgeToken, protected readonly config:
EthereumWalletConfig, readonly starknetWallet: WalletInterface, bridgeAbi:
InterfaceAbi = CANONICAL_BRIDGE_ABI, protected readonly logger: StarkZapLogger =
NOOP_LOGGER)), update any internal references to the constructor accordingly,
and keep the default values for CANONICAL_BRIDGE_ABI and NOOP_LOGGER so existing
callers passing a custom ABI as the fourth argument continue to work.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@examples/web/main.ts`:
- Around line 4447-4451: The code unsafely casts
document.getElementById("sdk-logs-toggle") to HTMLInputElement without a null
guard; update the block that declares sdkLogsToggle so you first obtain it as
HTMLInputElement | null (or let sdkLogsToggle = document.getElementById(...) as
HTMLInputElement | null) and then check for null before using it—e.g., if
sdkLogsToggle is null, skip wiring the listener or log/throw an error; otherwise
set sdkLogsVisible inside the sdkLogsToggle.addEventListener callback. Ensure
you only call addEventListener on the non-null sdkLogsToggle and keep the
sdkLogsVisible identifier as before.

In `@src/bridge/ethereum/cctp/CCTPFees.ts`:
- Around line 31-35: getInstance currently ignores subsequent logger arguments
because CCTPFees.instance is created once with the first logger; fix by removing
the long-lived singleton behavior so each call respects the provided logger:
update CCTPFees.getInstance to not return/reuse CCTPFees.instance (or implement
an instance-per-logger map keyed by logger identity) and ensure new
CCTPFees(logger) is constructed when a different logger is requested; adjust or
remove the static CCTPFees.instance field and any caller assumptions about a
global singleton so logger ownership is deterministic.

In `@src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts`:
- Around line 23-29: The interface HyperlaneSolanaMonitorOptions currently makes
logger required; revert it to optional to preserve backward compatibility by
changing the logger property on HyperlaneSolanaMonitorOptions back to an
optional type (e.g., logger?: StarkZapLogger) and ensure any consumer code in
the same file that reads logger (e.g., the SolanaHyperlaneMonitor constructor or
methods referenced around the later block at lines ~60-63) handles undefined by
using the existing silent/default logger fallback; update any typings or
parameter de-structuring that assumed logger is present so they use the optional
value or fallback logger.

In `@src/bridge/monitor/utils.ts`:
- Around line 26-27: The code logs routine monitoring states with logger.error
when returning BridgeTransferStatus.NOT_SUBMITTED_ON_STARKNET (and the similar
return at the other site), causing false-positive errors; change the severity of
those logs from logger.error(...) to a non-error level (e.g., logger.info(...)
or logger.debug(...)) for the cases that return
BridgeTransferStatus.NOT_SUBMITTED_ON_STARKNET and the other non-success status,
keeping error-level logging only for actual exceptions. Locate the
logger.error(...) calls that accompany the return of
BridgeTransferStatus.NOT_SUBMITTED_ON_STARKNET (and the analogous call at the
other return) and replace them with a lower-severity logger method while
preserving the message and txHash context.

In `@src/logger/index.ts`:
- Around line 152-155: The isLevelEnabled method returns true for level "silent"
when minPriority is lower than LEVEL_PRIORITY["silent"], which is misleading
because "silent" should always disable logging; update isLevelEnabled (in the
isLevelEnabled(level: LogLevel) method) to explicitly guard against the "silent"
level by returning false if level === "silent" (or equivalent value) before
comparing LEVEL_PRIORITY, so any call to isLevelEnabled("silent") always returns
false; reference LEVEL_PRIORITY and this.minPriority in the updated logic and
add a short comment explaining the guard.
- Around line 115-117: Update the JSDoc above the exported class StarkZapLogger
to clarify it's an internal implementation rather than part of the SDK public
API: change the comment to state that although StarkZapLogger is
module-exported, it is not re-exported from the SDK entry point and is intended
for internal use only (e.g., "Internal implementation. Exported from this module
but not re-exported from the public SDK entry point (src/index.ts)."). Ensure
the new comment mentions both the module-level export and the distinction from
the public API to avoid confusion.

In `@src/sdk.ts`:
- Around line 548-550: Add unit tests verifying SDK logging propagation for
getBridgingTokens(): write one test that constructs StarkZap (or the SDK class)
without a logging field in its config and asserts that calling
getBridgingTokens() produces no logger output (i.e., operates silently or uses a
no-op logger), and another test that constructs StarkZap with a custom logger in
config, calls getBridgingTokens(), and asserts the BridgeTokenRepository
created/used (BridgeTokenRepository instance stored as
this.bridgeTokenRepository) received that logger (or that createLogger was
called with the SDK config and BridgeTokenRepository calls went through the
provided logger). Use spies/mocks on createLogger and/or BridgeTokenRepository
methods to observe logger propagation from the SDK config into
getBridgingTokens().

---

Outside diff comments:
In `@src/bridge/ethereum/EthereumBridge.ts`:
- Around line 58-63: The constructor parameter order change breaks positional
callers: move the bridgeAbi parameter back to the 4th position and keep logger
as the 5th to restore backward compatibility (i.e., signature should be
constructor(protected readonly bridgeToken: EthereumBridgeToken, protected
readonly config: EthereumWalletConfig, readonly starknetWallet: WalletInterface,
bridgeAbi: InterfaceAbi = CANONICAL_BRIDGE_ABI, protected readonly logger:
StarkZapLogger = NOOP_LOGGER)), update any internal references to the
constructor accordingly, and keep the default values for CANONICAL_BRIDGE_ABI
and NOOP_LOGGER so existing callers passing a custom ABI as the fourth argument
continue to work.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ed2f40ad-9ebf-447b-bbd0-941b99c821fe

📥 Commits

Reviewing files that changed from the base of the PR and between 204251a and 72ab797.

📒 Files selected for processing (25)

• examples/web/index.html
• examples/web/main.ts
• packages/native/src/sdk.ts
• packages/native/src/wallet/cartridge.ts
• src/bridge/ethereum/EthereumBridge.ts
• src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts
• src/bridge/ethereum/cctp/CCTPBridge.ts
• src/bridge/ethereum/cctp/CCTPFees.ts
• src/bridge/ethereum/lords/LordsBridge.ts
• src/bridge/ethereum/oft/OftBridge.ts
• src/bridge/monitor/cctp/CctpMonitor.ts
• src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts
• src/bridge/monitor/oft/OftMonitor.ts
• src/bridge/monitor/utils.ts
• src/bridge/operator/BridgeOperator.ts
• src/bridge/tokens/repository.ts
• src/erc20/token/index.ts
• src/index.ts
• src/logger/index.ts
• src/sdk.ts
• src/types/config.ts
• src/wallet/base.ts
• src/wallet/cartridge.ts
• src/wallet/index.ts
• tests/bridge-token-repository.test.ts

📜 Review details

🧰 Additional context used

📓 Path-based instructions (7)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: Use @/ path alias for internal imports in TypeScript source files
Use strict TypeScript compiler settings: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes enabled

Files:

• src/wallet/cartridge.ts
• src/types/config.ts
• packages/native/src/wallet/cartridge.ts
• src/index.ts
• tests/bridge-token-repository.test.ts
• packages/native/src/sdk.ts
• src/bridge/ethereum/oft/OftBridge.ts
• src/bridge/tokens/repository.ts
• src/bridge/ethereum/cctp/CCTPBridge.ts
• src/bridge/monitor/oft/OftMonitor.ts
• src/bridge/ethereum/EthereumBridge.ts
• src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts
• src/bridge/ethereum/cctp/CCTPFees.ts
• src/wallet/base.ts
• src/erc20/token/index.ts
• src/wallet/index.ts
• src/sdk.ts
• src/bridge/monitor/utils.ts
• src/bridge/ethereum/lords/LordsBridge.ts
• src/bridge/monitor/cctp/CctpMonitor.ts
• src/bridge/operator/BridgeOperator.ts
• examples/web/main.ts
• src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts
• src/logger/index.ts

src/**/*.ts

📄 CodeRabbit inference engine (CLAUDE.md)

Preserve strict TypeScript typing; prefer explicit domain types (Address, Amount, ChainId) over primitives

Files:

• src/wallet/cartridge.ts
• src/types/config.ts
• src/index.ts
• src/bridge/ethereum/oft/OftBridge.ts
• src/bridge/tokens/repository.ts
• src/bridge/ethereum/cctp/CCTPBridge.ts
• src/bridge/monitor/oft/OftMonitor.ts
• src/bridge/ethereum/EthereumBridge.ts
• src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts
• src/bridge/ethereum/cctp/CCTPFees.ts
• src/wallet/base.ts
• src/erc20/token/index.ts
• src/wallet/index.ts
• src/sdk.ts
• src/bridge/monitor/utils.ts
• src/bridge/ethereum/lords/LordsBridge.ts
• src/bridge/monitor/cctp/CctpMonitor.ts
• src/bridge/operator/BridgeOperator.ts
• src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts
• src/logger/index.ts

**/*.{js,ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Do not introduce CommonJS patterns; use ESM only

Files:

• src/wallet/cartridge.ts
• src/types/config.ts
• packages/native/src/wallet/cartridge.ts
• src/index.ts
• tests/bridge-token-repository.test.ts
• packages/native/src/sdk.ts
• src/bridge/ethereum/oft/OftBridge.ts
• src/bridge/tokens/repository.ts
• src/bridge/ethereum/cctp/CCTPBridge.ts
• src/bridge/monitor/oft/OftMonitor.ts
• src/bridge/ethereum/EthereumBridge.ts
• src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts
• src/bridge/ethereum/cctp/CCTPFees.ts
• src/wallet/base.ts
• src/erc20/token/index.ts
• src/wallet/index.ts
• src/sdk.ts
• src/bridge/monitor/utils.ts
• src/bridge/ethereum/lords/LordsBridge.ts
• src/bridge/monitor/cctp/CctpMonitor.ts
• src/bridge/operator/BridgeOperator.ts
• examples/web/main.ts
• src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts
• src/logger/index.ts

{src/sdk.ts,src/wallet/**,src/types/**}

📄 CodeRabbit inference engine (AGENTS.md)

Must serialize: Concurrent edits in src/sdk.ts, src/wallet/*, or shared src/types/*

Files:

• src/wallet/cartridge.ts
• src/types/config.ts
• src/wallet/base.ts
• src/wallet/index.ts
• src/sdk.ts

src/**

⚙️ CodeRabbit configuration file

src/**: This is a public SDK. Prioritize:

• Backwards compatibility and clear, typed public APIs
• Deterministic behavior across mainnet/sepolia presets
• Tests for behavior changes (prefer unit tests)

Files:

• src/wallet/cartridge.ts
• src/types/config.ts
• src/index.ts
• src/bridge/ethereum/oft/OftBridge.ts
• src/bridge/tokens/repository.ts
• src/bridge/ethereum/cctp/CCTPBridge.ts
• src/bridge/monitor/oft/OftMonitor.ts
• src/bridge/ethereum/EthereumBridge.ts
• src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts
• src/bridge/ethereum/cctp/CCTPFees.ts
• src/wallet/base.ts
• src/erc20/token/index.ts
• src/wallet/index.ts
• src/sdk.ts
• src/bridge/monitor/utils.ts
• src/bridge/ethereum/lords/LordsBridge.ts
• src/bridge/monitor/cctp/CctpMonitor.ts
• src/bridge/operator/BridgeOperator.ts
• src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts
• src/logger/index.ts

src/index.ts

📄 CodeRabbit inference engine (CLAUDE.md)

Keep public API changes intentional and export them via src/index.ts

Must serialize: Any work touching src/index.ts (public API export surface)

Files:

• src/index.ts

tests/**

⚙️ CodeRabbit configuration file

tests/**: Integration tests can be flaky depending on devnet/RPC assumptions.
Prefer stable unit tests unless an integration test is strictly necessary.

Files:

• tests/bridge-token-repository.test.ts

🧠 Learnings (8)

📚 Learning: 2026-03-09T13:39:32.603Z

Learnt from: adrienlacombe
Repo: keep-starknet-strange/starkzap PR: 62
File: src/tx/builder.ts:449-539
Timestamp: 2026-03-09T13:39:32.603Z
Learning: Guideline for confidential transaction handling in StarkZap: In src/tx/builder.ts and src/confidential/types.ts, the sender field for confidential/tongo operations (ConfidentialFundDetails, ConfidentialTransferDetails, ConfidentialWithdrawDetails, ConfidentialRagequitDetails, ConfidentialRolloverDetails) represents the Starknet account submitting the transaction (often a relayer), not necessarily the wallet owner. The optional feeTo field is for relayed transactions where sender differs from the wallet.

Actionable checks for code reviews:
- Do not override details.sender with this.wallet.address in TxBuilder confidential methods; doing so breaks the relayer pattern.
- Ensure staking methods continue to bind this.wallet.address to reflect the pool member’s own address (no relayer concept there).
- If using a relayer, verify feeTo is set when appropriate and that sender remains the relayer address.
- Update or add tests to reflect the correct sender semantics for confidential operations...

Applied to files:

• src/wallet/cartridge.ts
• src/types/config.ts
• packages/native/src/wallet/cartridge.ts
• src/index.ts
• packages/native/src/sdk.ts
• src/bridge/ethereum/oft/OftBridge.ts
• src/bridge/tokens/repository.ts
• src/bridge/ethereum/cctp/CCTPBridge.ts
• src/bridge/monitor/oft/OftMonitor.ts
• src/bridge/ethereum/EthereumBridge.ts
• src/bridge/monitor/hyperlane/SolanaHyperlaneMonitor.ts
• src/bridge/ethereum/cctp/CCTPFees.ts
• src/wallet/base.ts
• src/erc20/token/index.ts
• src/wallet/index.ts
• src/sdk.ts
• src/bridge/monitor/utils.ts
• src/bridge/ethereum/lords/LordsBridge.ts
• src/bridge/monitor/cctp/CctpMonitor.ts
• src/bridge/operator/BridgeOperator.ts
• src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts
• src/logger/index.ts

📚 Learning: 2026-03-06T10:04:13.920Z

Learnt from: CR
Repo: keep-starknet-strange/starkzap PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-06T10:04:13.920Z
Learning: Applies to src/index.ts : Keep public API changes intentional and export them via `src/index.ts`

Applied to files:

• src/index.ts
• src/logger/index.ts

📚 Learning: 2026-03-06T10:04:28.285Z

Learnt from: CR
Repo: keep-starknet-strange/starkzap PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-06T10:04:28.285Z
Learning: Applies to src/index.ts : Must serialize: Any work touching `src/index.ts` (public API export surface)

Applied to files:

• src/index.ts

📚 Learning: 2026-03-09T13:42:08.400Z

Learnt from: adrienlacombe
Repo: keep-starknet-strange/starkzap PR: 62
File: tests/integration/confidential.test.ts:44-87
Timestamp: 2026-03-09T13:42:08.400Z
Learning: In `tests/integration/confidential.test.ts` (StarkZap, TypeScript/Vitest), the Confidential integration test suite intentionally spawns its own dedicated devnet (port 5110, loading `tongo-state/devnet.state`) instead of using the shared globalSetup devnet. This is because it requires a pre-built state dump with an already-deployed Tongo contract whose artifacts come from a separate repo and are baked in via `regenerate.mjs`. The shared devnet starts fresh (--seed 0, no contracts). The graceful warn+skip on devnet startup failure is intentional: if starknet-devnet is not installed or the state dump is missing, other tests should still pass. This is the accepted pattern for optional integration suites depending on external tooling in this project.

Applied to files:

• tests/bridge-token-repository.test.ts

📚 Learning: 2026-03-17T08:43:15.273Z

Learnt from: ZackAttax
Repo: keep-starknet-strange/starkzap PR: 86
File: packages/native/src/cartridge/ts/outside_execution_v3.ts:36-38
Timestamp: 2026-03-17T08:43:15.273Z
Learning: In `packages/native/src/cartridge/ts/outside_execution_v3.ts`, the `SESSION_TYPE_HASH` encodes only 4 fields ("Expires At", "Allowed Methods", "Metadata", "Session Key") while `hashSessionStruct` serializes 5 fields (adding `guardianKeyGuid`). This mismatch is intentional and inherited from the upstream Cartridge protocol (controller-rs / controller.c session token shape), where the same 4-field type-hash / 5-field payload pattern exists. Changing starkzap alone would break protocol parity and invalidate outside-execution signatures against live Cartridge contracts. This should only be fixed upstream as a coordinated/versioned protocol change.

Applied to files:

• packages/native/src/sdk.ts

📚 Learning: 2026-03-06T10:04:13.920Z

Learnt from: CR
Repo: keep-starknet-strange/starkzap PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-06T10:04:13.920Z
Learning: Applies to src/**/*.ts : Preserve strict TypeScript typing; prefer explicit domain types (Address, Amount, ChainId) over primitives

Applied to files:

• src/bridge/ethereum/cctp/CCTPFees.ts

📚 Learning: 2026-03-06T10:04:28.285Z

Learnt from: CR
Repo: keep-starknet-strange/starkzap PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-06T10:04:28.285Z
Learning: Applies to {src/sdk.ts,src/wallet/**,src/types/**} : Must serialize: Concurrent edits in `src/sdk.ts`, `src/wallet/*`, or shared `src/types/*`

Applied to files:

• src/wallet/base.ts
• examples/web/main.ts

📚 Learning: 2026-03-06T10:04:13.920Z

Learnt from: CR
Repo: keep-starknet-strange/starkzap PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-06T10:04:13.920Z
Learning: Applies to src/erc20/token/presets*.ts : Do not hand-edit auto-generated preset files: `src/erc20/token/presets.ts`, `src/erc20/token/presets.sepolia.ts`, `src/staking/validator/presets.ts`, `src/staking/validator/presets.sepolia.ts`

Applied to files:

• src/wallet/index.ts

🪛 HTMLHint (1.9.2)

examples/web/index.html

[warning] 1746-1746: No matching [ label ] tag found.

(input-requires-label)

🔇 Additional comments (34)

src/wallet/cartridge.ts (3)

32-32: LGTM!

Import correctly uses the @/ path alias for internal imports as per coding guidelines.

---

105-105: LGTM!

The optional logging property maintains backwards compatibility - existing callers are unaffected.

---

156-156: LGTM!

The conditional spread pattern is consistent with the existing approach used elsewhere in the constructor (e.g., for other optional configs) and correctly forwards the logging configuration to BaseWallet.

src/index.ts (1)

48-50: LGTM!

Type-only exports correctly expose the logging API surface. The grouping with a comment follows the established pattern in this file. As per coding guidelines, public API changes are intentional and exported via src/index.ts.

tests/bridge-token-repository.test.ts (3)

13-27: LGTM!

The mock logger helper is well-structured. It creates a StarkZapLogger with a no-op base logger and provides spies for assertion. The install() method pattern allows controlled setup and returns this for chaining.

---

253-268: LGTM!

Test correctly verifies that BridgeTokenRepository logs warnings through the injected logger when Solana runtime is unavailable. The assertion on mockLogger.spies.warn replaces the previous console.warn spy pattern.

---

283-296: LGTM!

Mirrors the pattern from the Solana test case, correctly verifying logger-based warning output when ethers is unavailable.

packages/native/src/wallet/cartridge.ts (3)

10-10: LGTM!

Import correctly references the main starkzap package's type export, which is appropriate for the native package.

---

251-251: LGTM!

Optional logging property maintains backwards compatibility with existing callers.

---

272-272: LGTM!

Conditional spread pattern is consistent with src/wallet/cartridge.ts and correctly forwards logging configuration to BaseWallet.

src/types/config.ts (2)

8-8: LGTM!

Import uses the @/ path alias correctly.

---

248-270: LGTM!

Excellent documentation with clear examples showing both quick debugging (console) and production usage (pino with level filter). The JSDoc accurately describes the default silent behavior and aligns with the PR objectives.

packages/native/src/sdk.ts (2)

52-53: LGTM!

Correctly destructures logging from getResolvedConfig(). The context snippet confirms that logging?: LoggerConfig is part of the resolved config shape returned by the parent class.

---

84-84: LGTM!

Conditional spread pattern is consistent with how bridging and staking are forwarded (lines 82-83), correctly propagating the logging configuration to the native wallet.

src/bridge/ethereum/oft/OftBridge.ts (2)

36-36: LGTM!

Import correctly uses the @/ path alias.

---

51-58: LGTM!

Constructor correctly accepts and forwards the logger to the EthereumBridge superclass. This follows the same pattern used in other bridge implementations (e.g., CanonicalEthereumBridge, LordsBridge).

src/bridge/monitor/oft/OftMonitor.ts (4)

21-21: LGTM!

Import correctly uses the @/ path alias.

---

45-45: LGTM!

The logger is correctly added as a required field in OftMonitorOptions. This is appropriate since monitors are instantiated by BridgeOperator, which always provides a logger instance.

---

54-54: LGTM!

Logger is properly stored as a private readonly field and assigned from constructor options.

Also applies to: 62-62

---

236-236: LGTM!

Correctly replaces console.debug with this.logger.debug, maintaining the same error-handling behavior (returns null on failure). This aligns with the PR's goal of replacing internal console calls with the pluggable logger.

src/bridge/ethereum/cctp/CCTPBridge.ts (2)

68-68: Downstream of existing singleton logger-capture issue.

Line 68 correctly passes this.logger, but it cannot take effect after first initialization because CCTPFees.getInstance(...) caches the initial logger. Root cause is in src/bridge/ethereum/cctp/CCTPFees.ts Lines 31-35.

---

138-141: Fee-estimation fallback logging migration looks good.

this.logger.debug(...) keeps behavior while aligning with the logger abstraction.

Also applies to: 195-198, 294-297

src/erc20/token/index.ts (1)

79-82: Logger propagation is clean and preserves silent-default behavior.

Optional logger threading is consistent, and Line 117 correctly guards emission when no logger is configured.

Also applies to: 117-122, 127-130, 152-152

src/bridge/tokens/repository.ts (1)

28-28: Good logger plumbing in repository warnings.

The NOOP default and this.logger.warn(...) substitutions are consistent and non-breaking for callers that omit logging config.

Also applies to: 253-253, 270-270, 353-356, 372-375, 407-407

examples/web/index.html (1)

616-637: Activity Log toggle integration is solid.

The sdk-logs-toggle control and associated styles are correctly structured for the existing web example log plumbing.

Also applies to: 1743-1749

src/wallet/base.ts (1)

138-143: Logger propagation in BaseWallet is correctly wired.

createLogger(options.logging) + passing this.logger into BridgeOperator is consistent and type-safe.

src/bridge/ethereum/lords/LordsBridge.ts (1)

19-33: LordsBridge constructor update is clean and consistent.

logger is threaded to CanonicalEthereumBridge in the correct position.

src/bridge/monitor/cctp/CctpMonitor.ts (1)

26-34: CCTP monitor logging migration looks correct.

Required logger injection and catch-path logging replacement are coherent with the new logging model.

Also applies to: 72-85, 291-292, 339-340, 371-372

src/wallet/index.ts (1)

142-149: Wallet logging passthrough is correctly integrated.

The optional logging config is forwarded to BaseWallet without affecting existing call paths.

Also applies to: 233-234

examples/web/main.ts (1)

216-221: Nice opt-in SDK trace integration for the playground.

The injected sdkLogger and hidden-by-default rendering behavior align well with the PR objective.

Also applies to: 223-242, 248-248

src/bridge/ethereum/canonical/CanonicalEthereumBridge.ts (1)

41-45: Canonical bridge logger migration is correctly implemented.

Constructor wiring and catch-path logging replacement are consistent across fee-estimation/error branches.

Also applies to: 189-192, 209-212, 283-286, 304-307

src/bridge/operator/BridgeOperator.ts (1)

55-59: BridgeOperator logger threading is complete and consistent.

All updated monitor/bridge instantiations receive this.logger in the expected positions.

Also applies to: 275-276, 313-314, 332-333, 404-406, 417-419, 424-424, 436-442

src/logger/index.ts (2)

1-33: Well-designed public API surface.

The Logger interface is minimal and compatible with console, pino, winston, and other popular loggers. The JSDoc examples are helpful for SDK consumers. Good use of lazy message evaluation via LogMessage type to avoid unnecessary serialization costs.

---

165-178: LGTM!

The NOOP_LOGGER singleton and createLogger factory correctly implement the documented resolution rules: silent when no config, all levels when config without logLevel, filtered when logLevel is provided.