Discovery
Some accounts can be found by calculation. Others cannot, and that difference shapes a surprising amount of this SDK.
Two kinds of address
Section titled “Two kinds of address”Many Solana accounts are program-derived: their address is computed from known inputs, so if you know the inputs you know the address without asking anyone.
Other accounts are created with an assigned address. Nothing about the surrounding data predicts it, so the only way to find one is to have recorded it, or to search.
In SAGE C4, several account types fall into the second group — the Game account itself, crafting processes, claim stake instances, and loot among them.
Why the API looks the way it does
Section titled “Why the API looks the way it does”This is why you see byCharacter, byBody, byProfile, and
forCharacterAtSystem rather than a single get(address) everywhere. Each of
those encodes one verified way of finding something.
The SDK does not paper over the difference by silently scanning the chain when a derivation is unavailable. A broad scan is expensive, slow, and easy to do by accident — so where a search is required, the API says so.
Providers
Section titled “Providers”Where discovery needs outside help, you supply it:
const sage = createSageClient({ cluster: 'zink-ptr', rpc, discovery: { walletProfiles },});A provider can be a lookup table you maintain, an indexer, or anything else
that can answer the question. Without one, the read that needs it fails with
RELATIONSHIP_NOT_DISCOVERABLE rather than guessing.
Indexers
Section titled “Indexers”An optional general indexer can supply address hints. Hints are validated before use — an indexer is an outside source, and the SDK treats it as untrusted input rather than as ground truth. A hint that does not check out is rejected rather than followed.
Where an indexer and the RPC disagree, the conservative default applies: the chain wins.
Practical advice
Section titled “Practical advice”If you are building something where users arrive with only a wallet address, solve discovery first. It has no free answer, and it shapes everything downstream. See identity for that specific case.
If you control the addresses you care about, you can avoid the problem entirely by starting from them.