dora-sdk-agent-usage

分类: 开发与编程 | 上传者: CityOfZion | 下载: 0 | 版本: v1.0（最新）
Guidance for agents using the Dora TypeScript SDK to query Dora/COZ blockchain data APIs safely and consistently.
更新日志: Source: GitHub https://github.com/CityOfZion/dora-sdk-ts
目录结构

当前层级: skills/dora-sdk-agent-usage/
📄 SKILL.md 8.8 KB
SKILL.md

---
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-13
---

# 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:

```ts
import { api, interfaces } from '@cityofzion/dora-ts'
```

Primary API clients:

```ts
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

1. Confirm the project is TypeScript/Node.js.
2. Confirm the data need matches an exported Dora client method.
3. Prefer importing the SDK instead of writing fresh HTTP request code.
4. Choose the correct chain client.
5. Pass the correct network explicitly when the environment is not obvious.
6. Handle request failures clearly rather than swallowing them.
7. If the endpoint is missing, propose extending the SDK rather than creating hidden one-off transport logic.
8. 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.
9. Use simple read-only smoke tests first, such as chain height or stats calls, before attempting more specialized history-export workflows.
10. 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.
11. 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.
12. 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

```ts
import { api } from '@cityofzion/dora-ts'

const balance = await api.NeoN3REST.balance(
  'Nb9QYTVx8F6j5kKi1k1ERaUTFfSX5JRq2D',
  'testnet'
)
```

### Neo X transaction lookup

```ts
import { api } from '@cityofzion/dora-ts'

const tx = await api.NeoXREST.getTransaction('0x1234...', 'mainnet')
```

### Unified full activity history

```ts
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:

```ts
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:

1. add the interface/type definitions first
2. implement the chain client method in the relevant `src/api/*/rest.ts`
3. export it from the chain index and package root if needed
4. add or update tests/examples
5. 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.
登录后下载/点赞/收藏 ❤ 6 | ★ 0
dora-sdk-agent-usage

目录结构

SKILL.md

举报内容

提示
