Add get_cashtoken_addresses to NetworkAPI by yashasvi-ranawat · Pull Request #161 · pybitcash/bitcash

yashasvi-ranawat · 2026-03-20T18:53:47Z

Description

Adds NetworkAPI.get_cashtoken_addresses(category_id) to fetch all BCH addresses currently holding unspent outputs of a given cashtoken category. The query is implemented via ChaingraphAPI's GraphQL interface and returns a set[str] of unique addresses.

Changes

Add get_cashtoken_addresses abstract method to BaseAPI
Implement in ChaingraphAPI using a GraphQL query on the output table filtered by token_category
Add NotImplementedError stubs in FulcrumProtocolAPI and BitcoinDotComAPI; NetworkAPI skips these transparently
Add optional filters: nft_capability: Optional[NFTCapability], nft_commitment: Optional[bytes], has_token: bool — translated to additional Chaingraph GraphQL where conditions
Document the feature in docs/guide/cashtokens.rst with usage examples for each filter
Add note in docs/guide/network.rst under NetworkAPI
Update README to mention CashToken and address subscription support

Adds a new method to fetch all addresses currently holding unspent outputs of a given cashtoken category. Implemented via ChaingraphAPI GraphQL query on the output table filtered by token_category. FulcrumProtocolAPI and BitcoinDotComAPI raise NotImplementedError, which NetworkAPI skips transparently. Returns a set[str] since address order is not meaningful. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…sses Allows callers to narrow results to addresses holding NFTs, a specific NFT commitment, or fungible tokens of a given cashtoken category. Filters are composable and translate to additional Chaingraph GraphQL where conditions; nft_commitment is passed as a typed bytea variable. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Allows filtering addresses by a specific NFT capability (none, mutable, minting) rather than a plain boolean. The capability enum name is passed as a typed enum_nonfungible_token_capability variable in the Chaingraph GraphQL query. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

yashasvi-ranawat · 2026-04-18T09:13:13Z

@merc1er This PR is ready. I'd want to merge this first before #163

merc1er

This looks great, thanks!

I tested with your example token category and was able to cross check with https://3xpl.com/bitcoin-cash/transaction/afe979e6b52e37d29f6c4d7edd922bddb91b5e4d55ebfa8cd59a0f90bc03b802 and https://tokenexplorer.cash/?tokenId=afe979e6b52e37d29f6c4d7edd922bddb91b5e4d55ebfa8cd59a0f90bc03b802.

I wonder what would happen with a token with a very large amount of holders, but I haven't tested this scenario.

Copilot

Pull request overview

Adds a new NetworkAPI.get_cashtoken_addresses(category_id, ...) API to retrieve the set of addresses currently holding unspent outputs for a given CashToken category, with optional Chaingraph-backed filters.

Changes:

Extends BaseAPI with get_cashtoken_addresses(...) and wires a NetworkAPI classmethod that falls back across configured endpoints.
Implements the query in ChaingraphAPI via GraphQL on output with optional nft_capability, nft_commitment, and has_token filters; adds stubs to other APIs.
Adds tests for Chaingraph behavior and updates docs/README to document the feature and usage.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`bitcash/network/services.py`	Adds `NetworkAPI.get_cashtoken_addresses` fallback method with filter passthrough.
`bitcash/network/APIs/__init__.py`	Adds abstract `BaseAPI.get_cashtoken_addresses` definition.
`bitcash/network/APIs/ChaingraphAPI.py`	Implements `get_cashtoken_addresses` using a Chaingraph GraphQL query and script→address decoding.
`bitcash/network/APIs/FulcrumProtocolAPI.py`	Adds `get_cashtoken_addresses` stub raising `NotImplementedError`.
`bitcash/network/APIs/BitcoinDotComAPI.py`	Adds `get_cashtoken_addresses` stub raising `NotImplementedError`.
`tests/network/APIs/test_ChaingraphAPI.py`	Adds unit tests for the new Chaingraph API method and filter query construction.
`tests/network/APIs/test_FulcrumProtolAPI.py`	Refactors test constants to reuse `tests.samples` values.
`docs/guide/network.rst`	Notes `NetworkAPI.get_cashtoken_addresses` is Chaingraph-only.
`docs/guide/cashtokens.rst`	Documents “CashToken holders” feature and filter usage examples.
`README.md`	Mentions CashToken support and real-time subscriptions in feature list.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

merc1er · 2026-04-27T02:43:17Z

@yashasvi-ranawat see if it makes sense to implement any of the feedback above. Otherwise happy to merge as-is.

Address.from_script now accepts a Network enum parameter (defaults to Network.main) so testnet/regtest addresses are encoded with the correct prefix and checksum. NetworkAPI.get_cashtoken_addresses passes the network through to the endpoint. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Add network: Network param to BaseAPI.__init__ and all concrete endpoint constructors. get_endpoints_for passes the correct Network enum at construction time, so ChaingraphAPI can use self.network in get_transaction and get_cashtoken_addresses without relying on kwargs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

yashasvi-ranawat · 2026-04-29T11:44:13Z

Good comments. I fixed them. Merge when ready :)

merc1er

🚀

Lists addresses holding tokens of a given category ID. Supports --nft-capability, --nft-commitment (hex), --has-amount, and --network filters. Now that get_cashtoken_addresses landed in master (PR pybitcash#161), the command is fully wired up. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

yashasvi-ranawat and others added 5 commits March 20, 2026 08:17

Fix nft_capability docstrings to reference NFTCapability enum

167d268

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Update README to mention CashToken and address subscription support

6233f33

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

yashasvi-ranawat changed the title ~~Feature/cashtoken addresses~~ Add get_cashtoken_addresses to NetworkAPI Mar 20, 2026

yashasvi-ranawat marked this pull request as ready for review March 20, 2026 18:58

yashasvi-ranawat and others added 3 commits March 20, 2026 21:03

Fix black formatting

236e0c1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'master' into feature/cashtoken-addresses

63dbee0

Run black formatting

bc41ad1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

merc1er requested review from Copilot and merc1er April 27, 2026 02:34

Copilot started reviewing on behalf of merc1er April 27, 2026 02:34 View session

merc1er approved these changes Apr 27, 2026

View reviewed changes

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Comment thread bitcash/network/APIs/ChaingraphAPI.py Outdated

Comment thread bitcash/network/services.py

Comment thread bitcash/network/services.py

yashasvi-ranawat and others added 7 commits April 28, 2026 22:10

Add NetworkAPI-level tests for get_cashtoken_addresses

80f6b45

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Update HISTORY.rst

adfcfb8

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Use sample fixtures in tests; add from_script network test

506a700

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Run black formatting

8778086

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix pyright error in mock_get_chaingraph_endpoints_for

9422130

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

merc1er approved these changes Apr 29, 2026

View reviewed changes

merc1er merged commit 7524cd6 into pybitcash:master Apr 29, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add get_cashtoken_addresses to NetworkAPI#161

Add get_cashtoken_addresses to NetworkAPI#161
merc1er merged 15 commits into
pybitcash:masterfrom
yashasvi-ranawat:feature/cashtoken-addresses

yashasvi-ranawat commented Mar 20, 2026 •

edited

Loading

Uh oh!

yashasvi-ranawat commented Apr 18, 2026

Uh oh!

merc1er left a comment •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

merc1er commented Apr 27, 2026

Uh oh!

yashasvi-ranawat commented Apr 29, 2026

Uh oh!

merc1er left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

yashasvi-ranawat commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Uh oh!

yashasvi-ranawat commented Apr 18, 2026

Uh oh!

merc1er left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

merc1er commented Apr 27, 2026

Uh oh!

yashasvi-ranawat commented Apr 29, 2026

Uh oh!

merc1er left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yashasvi-ranawat commented Mar 20, 2026 •

edited

Loading

merc1er left a comment •

edited

Loading