Registry class is your gateway to the Agora402 on-chain service directory. Every seller publishes a ServiceListing as an HCS topic message, and every buyer reads that same topic through the Hedera mirror node — no centralised database, no trusted operator. When you call listServices(), the class validates each listing’s ownership inline: if the account that paid for the HCS message does not match the listing’s payTo field, the entry is silently discarded, giving you tamper-resistant discovery without any registry authority.
Installation and Import
Constructor
Create oneRegistry instance per network. The mirror URL is derived automatically from network if you do not supply one.
Options
'testnet' | 'mainnet'
required
The Hedera network to connect to. Controls the default mirror node URL and the CAIP-2 prefix used to validate listings.
string
required
The HCS topic ID of the Agora402 registry, in
shard.realm.num format (e.g. 0.0.12345). All listings and delist messages are read from — and written to — this topic.string
Override the Hedera mirror node REST base URL. Defaults to the standard Hashio endpoint for the chosen network. Use this when running against a private mirror or a local devnet.
typeof fetch
Substitute a custom
fetch implementation. Useful for testing or for environments that require a proxy. Defaults to the global fetch.Methods
listServices()
- Messages that do not parse as a valid
RegistryMessageare skipped. - For
listingmessages, the HCS message payer must equallisting.payTo— entries that fail this check are dropped as spoofed. - The latest listing per UAID wins; any preceding
delistmessage for that UAID removes it from the result.
ServiceListing objects representing every active, verified seller.
Reading the registry requires no Hedera account or private key. All data is fetched from the public mirror node over HTTPS.
findEndpoint(endpointId, asset?)
listServices() internally, then filters to listings that expose an endpoint matching endpointId and that accept payments in asset. Returns an array of objects — one per matching seller — each containing the full listing and the matching endpoint descriptor.
string
required
The stable endpoint identifier to search for, e.g.
'infer' or 'hbar-rate'. Matched against EndpointSpec.id for every endpoint in every listing.string
The asset ID that the endpoint must accept, in
shard.realm.num format. Defaults to '0.0.0' (native HBAR). Pass an HTS token ID (e.g. '0.0.4567') to filter for token-denominated services.publishListing(client, listing)
listing as a RegistryMessage envelope and submits it to the HCS topic via the provided Hedera SDK Client. The SDK client’s operator account must match listing.payTo; if it does not, buyers will reject the listing as spoofed when they call listServices().
Client
required
An initialised
@hiero-ledger/sdk Client whose operator account is the seller’s payTo account. The HCS message is signed and paid by this account.ServiceListing
required
The fully-populated
ServiceListing object. The payTo field must equal the operator account ID of client. The listing is validated before submission; invalid listings throw synchronously.delist(client, uaid, reason?)
delist message to the HCS topic. After the message achieves consensus, listServices() will exclude the listing. Only the account that originally published the listing (i.e. the operator of client) can delist it — the same HCS-payer-equals-payTo rule applies.
Client
required
The Hedera SDK
Client whose operator is the original listing’s payTo account.string
required
The HCS-14 UAID of the listing to remove, e.g.
'uaid:aid:...'.string
An optional human-readable reason string written into the delist message, useful for audit trails. Examples:
'maintenance', 'deprecated'.Trust Model
Agora402 uses no registry operator and no admin key. Listing ownership is proven entirely through the HCS consensus mechanism: the account that pays the HCS message fee must be the same account that receives payments (payTo). This binding means:
- A seller cannot impersonate another seller’s
payToaccount without controlling that account’s private key. - Any account can publish a listing for itself at any time without permission from a central authority.
- Any account can delist only its own listings.
This trust model is enforced client-side in
listServices(). The on-chain topic itself is permissionless — the safety guarantee lives in the buyer’s verification logic, not in topic access controls.