feat: support read-only address queries for balance and staking position

[0xLucqs]

Summary by CodeRabbit

Release Notes

• Chores

  • Simplified package naming convention

• New Features

  • Enhanced wallet input flexibility: methods now accept raw addresses or objects alongside wallet interface objects

• Refactor

  • Extracted validation logic into reusable utility functions for improved code maintainability
  • Updated method signatures to support broader input types

• Tests

  • Added comprehensive test coverage for wallet address handling and amount validation

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 880beac9-8df1-4eaf-8af6-67d873e1803d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Warning

.coderabbit.yaml has a parsing error

The CodeRabbit configuration file in this repository has a parsing error and default settings were used instead. Please fix the error(s) in the configuration file. You can initialize chat with CodeRabbit to get help with the configuration file.

💥 Parsing errors (1)

Validation error: Number must be less than or equal to 900000 at "reviews.tools.github-checks.timeout_ms"

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

📝 Walkthrough

Walkthrough

The pull request simplifies the package name from scoped (@keep-starknet-strange/starkzap-mcp) to non-scoped (starkzap-mcp) across package metadata, extracts token amount validation and wallet address resolution into reusable type utilities, refactors ERC20 and Staking classes to use these utilities instead of internal validation, and adds test coverage for address resolution and position queries.

Changes

Cohort / File(s)	Summary
Package Metadata packages/mcp-server/README.md, packages/mcp-server/package.json, packages/mcp-server/src/index.ts	Simplified package name from scoped (@keep-starknet-strange/starkzap-mcp) to non-scoped (starkzap-mcp) in package definition and documentation references.
Type Utilities src/types/address.ts, src/types/amount.ts	Added resolveWalletAddress() function and AddressInput type for flexible wallet/address parameter handling; added assertAmountMatchesToken() function for centralized token amount validation.
Core Refactoring src/erc20/erc20.ts, src/staking/staking.ts	Removed private validation methods and updated multiple method signatures to accept WalletInterface | Address | BigNumberish via resolveWalletAddress(); replaced internal amount validation calls with external assertAmountMatchesToken() utility across various public methods.
Test Coverage tests/erc20.test.ts, tests/staking-auto-stake.test.ts, tests/staking-readonly.test.ts	Added test cases for balanceOf() accepting raw address strings and address objects; updated mock staking objects to expose token property; added comprehensive getPosition() test suite covering address string, address object, and wallet interface inputs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A scoped name becomes one true and light,
Validation extracted to shine so bright,
Addresses resolved in many a way,
Type utils dance and refactoring play,
Tests bloom anew to show it's all right! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding support for read-only address queries (accepting raw addresses and address objects) for both balance and staking position queries.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/fix-issue-58-readonly-address

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

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.}