| name | dora-sdk-agent-usage |
| description | Guidance for agents using the Dora TypeScript SDK to query Dora/COZ blockchain data APIs safely and consistently. |
| owner | City of Zion |
| status | draft |
| last_reviewed | "2026-03-13T00:00:00.000Z" |
Dora SDK Agent Usage
Use this skill when an agent needs blockchain data from the Dora platform and the task is happening in a TypeScript or Node.js codebase.
Why agents should use this SDK
Agents should prefer this SDK over ad hoc raw HTTP calls when working in TypeScript because it provides:
- a stable typed wrapper around Dora REST endpoints
- consistent chain-specific clients for Neo N3, Neo Legacy, Neo X, and Ethereum
- reusable unified activity-history methods across supported protocols
- lower implementation risk than hand-assembling endpoint URLs and payloads
- clearer code for future maintainers than scattered
axios calls
Use the SDK especially when the goal is to:
- fetch balances, blocks, transactions, contracts, or address activity
- export activity history CSVs
- build tooling, scripts, or services that consume Dora data repeatedly
- keep protocol-specific access patterns readable and typed
When not to use this SDK
Do not force this SDK into tasks where it is a poor fit.
Avoid or reconsider it when:
- the task is not in TypeScript/Node.js
- the required Dora endpoint is not exposed by the current SDK surface
- the user only needs a one-off manual inspection and not code integration
- the project requires lower-level transport customization beyond what the SDK exposes
In those cases, either extend the SDK deliberately or document why direct API access is required.
What the SDK exposes
Top-level package exports:
import { api, interfaces } from '@cityofzion/dora-ts'
Primary API clients:
api.NeoN3REST
api.NeoLegacyREST
api.NeoXREST
api.EthereumREST
Supported chain surfaces
Neo N3
Use api.NeoN3REST for common Neo N3 explorer/data workflows such as:
addressTransactions(address, page?, network?)balance(address, network?)block(blockHeight, network?)blocks(page?, network?)contract(contractHash, network?)contracts(page, network?)contractStats(contractHash, network?)height(network?)invocationStats(network?)log(txid, network?)tokenProvenance(contract, tokenId, network?)transaction(txid, network?)transactions(page?, network?)transferHistory(address, page?, network?)voter(address, network?)getFullTransactionsByAddress(params)exportFullTransactionsByAddress(params)
Neo Legacy
Use api.NeoLegacyREST for Neo2 / legacy explorer workflows such as:
addressStats(address, network?)asset(assetHash, network?)assets(page?, network?)balance(address, network?)block(blockHash, network?)blocks(page?, network?)contract(contractHash, network?)contracts(page, network?)contractTransfers(contractHash, page?, network?)getAddressAbstracts(address, page?, network?)getAllNodes(network?)getUnclaimed(address, network?)height(network?)invocationStats(network?)log(contractHash, network?)storage(blockHash, network?)transaction(txid, network?)transactions(page?, network?)transactionAbstracts(txid, network?)transferHistory(address, page?, network?)getFullTransactionsByAddress(params)exportFullTransactionsByAddress(params)
Neo X
Use api.NeoXREST for Neo X explorer/data queries such as:
getAddress(addressHash, network?)getBlock(blockNumberOrHash, network?)getBlocks(network?)getStats(network?)getTokens(network?)getTransaction(transactionHash, network?)getFullTransactionsByAddress(params)exportFullTransactionsByAddress(params)
Ethereum
Use api.EthereumREST for unified activity-history workflows currently exposed by the SDK:
getFullTransactionsByAddress(params)exportFullTransactionsByAddress(params)
Recommended agent workflow
- Confirm the project is TypeScript/Node.js.
- Confirm the data need matches an exported Dora client method.
- Prefer importing the SDK instead of writing fresh HTTP request code.
- Choose the correct chain client.
- Pass the correct network explicitly when the environment is not obvious.
- Handle request failures clearly rather than swallowing them.
- If the endpoint is missing, propose extending the SDK rather than creating hidden one-off transport logic.
- When validating this skill itself, test it in a fresh Node app that installs the published npm package
@cityofzion/dora-ts rather than wiring the SDK from a local repo checkout.
- Use simple read-only smoke tests first, such as chain height or stats calls, before attempting more specialized history-export workflows.
- For Neo N3 address analysis, prefer starting with
balance, addressTransactions, and voter because these have been the most reliable read-only surfaces in fresh-app validation.
- Treat
transferHistory and getFullTransactionsByAddress as higher-risk follow-on methods during exploratory address work; probe them after baseline methods succeed and capture exact status/error behavior if they fail.
- When the goal is behavioral analysis rather than export completeness, derive a first-pass activity view from
addressTransactions.items[*].transfers and addressTransactions.items[*].invocations before escalating to heavier history endpoints.
Example usage
Neo N3 balance lookup
import { api } from '@cityofzion/dora-ts'
const balance = await api.NeoN3REST.balance(
'Nb9QYTVx8F6j5kKi1k1ERaUTFfSX5JRq2D',
'testnet'
)
Neo X transaction lookup
import { api } from '@cityofzion/dora-ts'
const tx = await api.NeoXREST.getTransaction('0x1234...', 'mainnet')
Unified full activity history
import { api } from '@cityofzion/dora-ts'
const history = await api.NeoN3REST.getFullTransactionsByAddress({
address: 'Nb9QYTVx8F6j5kKi1k1ERaUTFfSX5JRq2D',
page: 1,
network: 'mainnet'
})
Implementation guidance for agents
Prefer patterns like this:
import { api } from '@cityofzion/dora-ts'
export async function getAddressActivity(address: string) {
return await api.NeoN3REST.getFullTransactionsByAddress({
address,
page: 1,
network: 'mainnet'
})
}
Avoid replacing the SDK with custom axios code unless one of these is true:
- the method does not exist in the SDK
- the SDK behavior is incorrect and needs a fix
- the task explicitly requires raw endpoint experimentation
Good agent behaviors
- Use chain-specific SDK clients intentionally.
- Keep network selection explicit where possible.
- Reuse SDK response types when building application code.
- Keep wrappers thin; do not duplicate SDK logic without reason.
- If you add a new endpoint, add typings and examples with it.
Watchouts
- Neo N3 and Neo Legacy have different method names and semantics.
- Some methods use hashes, others use block heights or addresses; do not guess inputs.
- Unified activity-history methods are protocol-backed and set protocol internally.
- README guidance in this repo is currently light; inspect exported modules and implementation before claiming support for an endpoint.
- A successful install may still report third-party
npm audit warnings; do not confuse dependency audit output with proof that the SDK import or basic read-only API usage is broken.
- Validate package usability with a minimal import-and-query smoke test before escalating install-time warnings as SDK failures.
- In fresh-app Neo N3 validation,
addressTransactions has been useful not just for transaction lists but also for lightweight first-pass behavior analysis via embedded transfers and invocations data.
- Do not assume history-oriented Neo N3 methods are equally reliable for every address or environment; observed failures included
transferHistory returning 503 during otherwise successful address analysis.
- In fresh-app validation,
getFullTransactionsByAddress returned 400 network is required when called without network in the params object. Do not assume this method inherits the same network-handling pattern as simpler position-argument methods; pass network explicitly in the params.
- When these higher-order history methods fail, report the exact method, input shape, network, and returned status/message instead of collapsing the result into a generic “SDK broken” claim.
If extending this SDK
When agents need an unsupported endpoint:
- add the interface/type definitions first
- implement the chain client method in the relevant
src/api/*/rest.ts
- export it from the chain index and package root if needed
- add or update tests/examples
- document the new capability in the README and this skill
Repository-specific note
This repo’s current default branch is develop. If contributing changes, branch from develop and open PRs back into develop unless a maintainer instructs otherwise.
