zramsay/zenith-docs
1
0
Fork 0
Code Pull Requests Activity

docs mvp

Browse Source
This commit is contained in:
zramsay
2025-11-28 15:34:21 -05:00
committed by zramsay
commit 00424e7cda
34 changed files with 4689 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/azimuth-watcher.md
+351
View File
@@ -0,0 +1,351 @@
# Azimuth Watcher API
The Azimuth Watcher monitors Urbit's Azimuth identity registry on Ethereum, providing access to point ownership, sponsorship relationships, and identity state changes.
**GraphQL Endpoint**: `https://azimuth-watcher.zenith-test.tlon.systems/graphql`
## Querying Urbit Point Information
The azimuth-watcher is the primary service for querying Urbit identity data. Here are the most common operations:
### 1. Get Point Owner and Basic Info
Check who owns a specific Urbit point:
```bash
# Example:
curl 'https://azimuth.dev.vdb.to/graphql' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"{ azimuthGetOwner(blockHash: \"latest\", contractAddress: \"0x223c067F8CF28ae173EE5CafEa60cA44C335fecB\", _point: 1234) { value } }"}' \
| jq
```
**Response:**
```json
{
"data": {
"azimuthGetOwner": {
"value": "0x4b22764F2Db640aB4d0Ecfd0F84344F3CB5C3715"
}
}
}
```
### 2. Get Cryptographic Keys for a Point
Get encryption and authentication keys for networking:
```bash
# Example:
curl 'https://azimuth.dev.vdb.to/graphql' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"{ azimuthGetKeys(blockHash: \"latest\", contractAddress: \"0x223c067F8CF28ae173EE5CafEa60cA44C335fecB\", _point: 58213) { value { encryptionKey: value0 authenticationKey: value1 cryptoSuiteVersion: value2 keyRevisionNumber: value3 } } }"}' \
| jq
```
**Response:**
```json
{
"data": {
"azimuthGetKeys": {
"value": {
"encryptionKey": "0xc248f759474b16192bd8bdca0bff1b8bff555cd3d118022095331d6d98690c6d",
"authenticationKey": "0x21188bac08542730e1c4697636d6fa25968f404470ccf917756f05e28c69045a",
"cryptoSuiteVersion": "1",
"keyRevisionNumber": "1"
}
}
}
}
```
### 3. Check Point Status
Check if a point is active (booted) and has a sponsor:
```bash
# Example:
curl 'https://azimuth.dev.vdb.to/graphql' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"{ azimuthIsActive(blockHash: \"latest\", contractAddress: \"0x223c067F8CF28ae173EE5CafEa60cA44C335fecB\", _point: 1234) { value } azimuthHasSponsor(blockHash: \"latest\", contractAddress: \"0x223c067F8CF28ae173EE5CafEa60cA44C335fecB\", _point: 1234) { value } azimuthGetSponsor(blockHash: \"latest\", contractAddress: \"0x223c067F8CF28ae173EE5CafEa60cA44C335fecB\", _point: 1234) { value } }"}' \
| jq
```
**Response:**
```json
{
"data": {
"azimuthIsActive": {
"value": true
},
"azimuthHasSponsor": {
"value": true
},
"azimuthGetSponsor": {
"value": "210"
}
}
}
```
### 4. Get All Points Owned by an Address
Find all Urbit points owned by an Ethereum address:
```bash
# Example:
curl 'https://azimuth.dev.vdb.to/graphql' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"{ azimuthGetOwnedPoints(blockHash: \"latest\", contractAddress: \"0x223c067F8CF28ae173EE5CafEa60cA44C335fecB\", _whose: \"0x1234567890123456789012345678901234567890\") { value } }"}' \
| jq
```
**Response:**
```json
{
"data": {
"azimuthGetOwnedPoints": {
"value": [
"57965",
"1234"
]
}
}
}
```
### 5. Multi-Watcher Queries
The gateway server allows querying multiple watchers in a single request:
```graphql
{
# Check point status (azimuth-watcher)
azimuthIsActive(
blockHash: "0x2461e78f075e618173c524b5ab4309111001517bb50cfd1b3505aed5433cf5f9"
contractAddress: "0x223c067F8CF28ae173EE5CafEa60cA44C335fecB"
_point: 1
) {
value
}
# Check censure count (censures-watcher)
censuresGetCensuredByCount(
blockHash: "0x2461e78f075e618173c524b5ab4309111001517bb50cfd1b3505aed5433cf5f9"
contractAddress: "0x325f68d32BdEe6Ed86E7235ff2480e2A433D6189"
_who: 6054
) {
value
}
# Find a claim (claims-watcher)
claimsFindClaim(
blockHash: "0x2461e78f075e618173c524b5ab4309111001517bb50cfd1b3505aed5433cf5f9"
contractAddress: "0xe7e7f69b34D7d9Bd8d61Fb22C33b22708947971A"
_whose: 1967913144
_protocol: "text"
_claim: "Shrek is NOT Drek!"
) {
value
}
# Check star release balance (linear-star-release-watcher)
linearStarReleaseVerifyBalance(
blockHash: "0x2461e78f075e618173c524b5ab4309111001517bb50cfd1b3505aed5433cf5f9"
contractAddress: "0x86cd9cd0992F04231751E3761De45cEceA5d1801"
_participant: "0xbD396c580d868FBbE4a115DD667E756079880801"
) {
value
}
# Check conditional star release (conditional-star-release-watcher)
conditionalStarReleaseWithdrawLimit(
blockHash: "0x2461e78f075e618173c524b5ab4309111001517bb50cfd1b3505aed5433cf5f9"
contractAddress: "0x8C241098C3D3498Fe1261421633FD57986D74AeA"
_participant: "0x7F0584938E649061e80e45cF88E6d8dDDb22f2aB"
_batch: 2
) {
value
}
# Check governance proposals (polls-watcher)
pollsGetUpgradeProposalCount(
blockHash: "0xeaf611fabbe604932d36b97c89955c091e9582e292b741ebf144962b9ff5c271"
contractAddress: "0x7fEcaB617c868Bb5996d99D95200D2Fa708218e4"
) {
value
}
# Check NFT balance (ecliptic-watcher)
eclipticBalanceOf(
blockHash: "0x5e82abbe6474caf7b5325022db1d1287ce352488b303685493289770484f54f4"
contractAddress: "0x33EeCbf908478C10614626A9D304bfe18B78DD73"
_owner: "0x4b5E239C1bbb98d44ea23BC9f8eC7584F54096E8"
) {
value
}
# Check delegation permissions (delegated-sending-watcher)
delegatedSendingCanSend(
blockHash: "0x2461e78f075e618173c524b5ab4309111001517bb50cfd1b3505aed5433cf5f9"
contractAddress: "0xf6b461fE1aD4bd2ce25B23Fe0aff2ac19B3dFA76"
_as: 1
_point: 1
) {
value
}
}
```
## Understanding Query Parameters
All queries require these standard parameters:
- **blockHash**: Use `"latest"` for current state, or a specific block hash for historical queries
- **contractAddress**: Azimuth contract address (`0x223c067F8CF28ae173EE5CafEa60cA44C335fecB`)
- **_point**: The Urbit point number you're querying
- **_whose**: Ethereum address when querying by owner
## How It Works
### Data Source
The watchers continuously monitor Ethereum smart contracts by connecting to Ethereum RPC endpoint(s), indexing blockchain events and state changes.
### Data Flow
1. **Indexing**: Job runners fetch Ethereum events and blocks from RPC endpoint(s)
2. **Processing**: Events are processed and state changes stored in PostgreSQL databases
3. **Querying**: GraphQL servers provide fast, indexed access to current and historical blockchain state
4. **Gateway**: Unified endpoint routes queries to appropriate specialized watchers
### Storage
Each watcher maintains its own PostgreSQL database for efficient querying and data isolation.
## Additional Query Examples
### Query Point Information
```graphql
query GetPoint($point: String!) {
point(id: $point) {
id
owner
sponsor
keyRevisionNumber
managementProxy
spawnProxy
votingProxy
transferProxy
active
escapeRequested
escapeRequestedTo
}
}
```
## Query Point History
```graphql
query GetPointHistory($point: String!) {
point(id: $point) {
id
transfers {
timestamp
from
to
blockNumber
}
spawns {
timestamp
child
blockNumber
}
}
}
```
## Query Multiple Points
```graphql
query GetPoints($owner: String!) {
points(where: { owner: $owner }) {
id
owner
sponsor
active
}
}
```
## Using the GraphQL API
### With curl
```bash
# Query Azimuth Watcher
curl -X POST https://azimuth-watcher.zenith-test.tlon.systems/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "query { point(id: \"~sampel-palnet\") { owner sponsor } }"
}'
```
### With JavaScript/TypeScript
```javascript
const query = `
query GetPoint($point: String!) {
point(id: $point) {
owner
sponsor
active
}
}
`;
const variables = { point: "~sampel-palnet" };
const response = await fetch('https://azimuth-watcher.zenith-test.tlon.systems/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query, variables })
});
const data = await response.json();
```
### With GraphQL Client Libraries
```javascript
import { GraphQLClient } from 'graphql-request';
const client = new GraphQLClient(
'https://azimuth-watcher.zenith-test.tlon.systems/graphql'
);
const query = `
query GetPoint($point: String!) {
point(id: $point) {
owner sponsor active
}
}
`;
const data = await client.request(query, { point: '~sampel-palnet' });
```
## Rate Limiting and Best Practices
- **Rate Limits**: Public watcher endpoints have rate limiting in place. For production applications, consider running your own watcher instances.
- **Pagination**: Use pagination parameters for queries that return large result sets.
- **Caching**: Cache frequently accessed data to reduce API load.
- **Error Handling**: Implement proper error handling and retry logic for network failures.
!!! note "Watcher Documentation"
For more information about the watcher architecture and deployment, see the [Watchers documentation](../documentation/watchers.md).
docs/api/index.md
+36
View File
@@ -0,0 +1,36 @@
# API Reference
This section provides comprehensive API documentation for interacting with the Zenith network and developing applications on top of the Zenith ecosystem.
## Available APIs
### Zenith Desk API
The [Zenith Desk API](zenith-desk-api.md) provides developers with tools and libraries for building Urbit applications that integrate with the Zenith blockchain. This API enables seamless interaction between Urbit ships and Zenith's consensus layer.
### zenithd API
The [zenithd API](zenithd.md) provides REST endpoints for querying blockchain state, account information, and module-specific data. Includes comprehensive HTTP/RPC query examples for all Zenith modules.
### Janus API
The [Janus API](janus.md) provides HTTP endpoints for transaction bundling and scry binding submission. Galaxy endpoints accept bundles from stars, while star endpoints accept transactions and scry bindings from planets.
### Watchers API
The Watchers provide GraphQL and REST interfaces for querying indexed blockchain data:
- **[Azimuth Watcher](azimuth-watcher.md)**: Query Urbit point ownership, sponsorship, and identity data
- **[Lockdrop Watcher](lockdrop-watcher.md)**: Query lockdrop deposits and commitments
- **[Zenith Watcher](zenith-watcher.md)**: Query Zenith blockchain data including accounts, transactions, validators, and scry bindings
## Getting Started
Choose the appropriate API based on your use case:
- **Building Urbit Applications**: Start with the [Zenith Desk API](zenith-desk-api.md)
- **Querying Blockchain State**: Use the [zenithd API](zenithd.md) for HTTP/REST queries
- **Indexed Urbit Identity Data**: Use the [Azimuth Watcher](azimuth-watcher.md) for GraphQL queries
- **Lockdrop Information**: Use the [Lockdrop Watcher](lockdrop-watcher.md) for GraphQL queries
- **Zenith Blockchain Data**: Use the [Zenith Watcher](zenith-watcher.md) for GraphQL and REST queries
- **Transaction Bundling**: Use the [Janus API](janus.md) for galaxy and star operations
## API Documentation Status
API documentation is actively being developed. Check individual pages for the latest specifications, examples, and integration guides.
docs/api/janus.md
+183
View File
@@ -0,0 +1,183 @@
# Janus Server API
The Janus server provides HTTP endpoints for accepting transaction bundles and scry bindings. The Janus server runs in-process for galaxy validators and as part of zenithd in star mode. Endpoints are available based on the node's operational mode.
## Galaxy Endpoints
Galaxy endpoints are only available when zenithd is running in galaxy mode. These endpoints accept protobuf-encoded data.
### Submit Transaction Bundle
```bash
# Submit a protobuf-encoded bundle from a star
# The bundle includes star ID, transactions, and star signature
curl -X POST http://localhost:8080/api/galaxy/submit/bundle \
-H "Content-Type: application/octet-stream" \
--data-binary @bundle.pb
```
**Response:**
```json
{
"success": true,
"message": "Bundle processed successfully",
"bundle_id": "bundle-uuid"
}
```
### Submit Scry Binding Batch
```bash
# Submit a protobuf-encoded scry batch from a star
# Includes star ID, scry bindings with individual signatures
curl -X POST http://localhost:8080/api/galaxy/submit/scry \
-H "Content-Type: application/octet-stream" \
--data-binary @scry_batch.pb
```
**Response:**
```json
{
"success": true,
"message": "Scry bindings processed successfully",
"star_id": "12345",
"bindings_processed": 10
}
```
### Queue Status
```bash
# Get current bundle queue status (galaxy mode only)
curl http://localhost:8080/api/galaxy/queue/status
```
**Response:**
```json
{
"pending_bundles": 5,
"size_mb": 2.3,
"max_size_mb": 100
}
```
### Galaxy Health Check
```bash
# Check galaxy Janus server health
curl http://localhost:8080/api/galaxy/health
```
**Response:**
```json
{
"status": "healthy",
"server": "janus",
"node_mode": "galaxy"
}
```
## Star Endpoints
Star endpoints are available when zenithd is running in star or galaxy mode. These endpoints accept transactions and scry bindings from planets.
### Submit Transaction
```bash
# Submit a protobuf-encoded transaction from a planet
curl -X POST http://localhost:8080/api/star/submit/tx \
-H "Content-Type: application/octet-stream" \
--data-binary @transaction.pb
```
**Response:**
```json
{
"success": true,
"message": "Transaction queued for bundling"
}
```
### Submit Scry Binding
```bash
# Submit a scry binding with Ed25519 signature
curl -X POST http://localhost:8080/api/star/submit/scry \
-H "Content-Type: application/json" \
-d '{
"scry-binding": {
"path": "/~sampel-palnet/app/data",
"hash": "0xabc123...",
"signature": "0xdef456...",
"life": 1
}
}'
```
**Response:**
```json
{
"success": true,
"message": "Scry binding queued for submission"
}
```
### Star Status
```bash
# Get star node operational status
curl http://localhost:8080/api/star/status
```
**Response:**
```json
{
"success": true,
"data": {
"node_type": "star",
"star_id": 12345,
"timestamp": "2024-01-01T00:00:00Z",
"pending_transactions": 5,
"pending_scry_bindings": 3,
"galaxy_url": "https://galaxy.example.com",
"max_tx_per_bundle": 100,
"bundle_timeout": "30s",
"scry_batch_size": 50,
"scry_batch_timeout": "60s",
"require_signatures": true
}
}
```
### Star Health Check
```bash
# Check star Janus server health
curl http://localhost:8080/api/star/health
```
**Response:**
```json
{
"status": "healthy",
"server": "janus",
"node_mode": "star",
"zenith_key_loaded": true
}
```
!!! note "Janus Configuration"
The Janus server configuration (port, endpoints, etc.) is managed through the zenithd configuration file. See the [Janus documentation](../documentation/janus.md) for more details on the transaction aggregation architecture.
!!! warning "Mode Restrictions"
- Galaxy endpoints (`/api/galaxy/*`) only work in galaxy mode
- Star endpoints (`/api/star/*`) work in both star and galaxy modes
- Attempting to access galaxy endpoints in star mode returns a 403 Forbidden error
docs/api/lockdrop-watcher.md
+115
View File
@@ -0,0 +1,115 @@
# Lockdrop Watcher API
The Lockdrop Watcher monitors the Zenith lockdrop contract on Ethereum, tracking participant deposits and lock commitments during Stage 0.
**GraphQL Endpoint**: `https://lockdrop-watcher.zenith-test.tlon.systems/graphql`
## Query Deposit Information
```graphql
query GetDeposit($address: String!) {
deposit(address: $address) {
address
points
lockDuration
timestamp
blockNumber
transactionHash
}
}
```
## Query All Deposits
```graphql
query GetAllDeposits {
deposits(orderBy: timestamp, orderDirection: desc) {
address
points
lockDuration
timestamp
}
}
```
## Query Locked Points
```graphql
query GetLockedPoints($pointId: Int!) {
lockedPoint(id: $pointId) {
pointId
owner
lockDuration
lockedAt
unlocksAt
withdrawn
}
}
```
## Using the GraphQL API
### With curl
```bash
# Query Lockdrop Watcher
curl -X POST https://lockdrop-watcher.zenith-test.tlon.systems/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "query { deposits { address points lockDuration } }"
}'
```
### With JavaScript/TypeScript
```javascript
const query = `
query GetDeposit($address: String!) {
deposit(address: $address) {
points
lockDuration
timestamp
}
}
`;
const variables = { address: "0x..." };
const response = await fetch('https://lockdrop-watcher.zenith-test.tlon.systems/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query, variables })
});
const data = await response.json();
```
### With GraphQL Client Libraries
```javascript
import { GraphQLClient } from 'graphql-request';
const client = new GraphQLClient(
'https://lockdrop-watcher.zenith-test.tlon.systems/graphql'
);
const query = `
query GetDeposit($address: String!) {
deposit(address: $address) {
points lockDuration timestamp
}
}
`;
const data = await client.request(query, { address: '0x...' });
```
## Rate Limiting and Best Practices
- **Rate Limits**: Public watcher endpoints have rate limiting in place. For production applications, consider running your own watcher instances.
- **Pagination**: Use pagination parameters for queries that return large result sets.
- **Caching**: Cache frequently accessed data to reduce API load.
- **Error Handling**: Implement proper error handling and retry logic for network failures.
!!! note "Watcher Documentation"
For more information about the watcher architecture and deployment, see the [Watchers documentation](../documentation/watchers.md).
docs/api/zenith-desk-api.md
+1202
View File
File diff suppressed because it is too large Load Diff
docs/api/zenith-watcher.md
+404
View File
@@ -0,0 +1,404 @@
# Zenith Watcher API
The Zenith Watcher indexes the Zenith blockchain across all network stages, providing access to account information, transactions, validators, scry bindings, and treasury claims.
**GraphQL Endpoint**: `https://zenith-watcher.zenith-test.tlon.systems/graphql`
## GraphQL API
### Query Account Information
```graphql
query GetAccount($address: String!) {
account(address: $address) {
address
balances {
denom
amount
}
transactions {
hash
type
timestamp
blockHeight
success
}
}
}
```
### Query Transactions
```graphql
query GetTransactions($address: String!, $limit: Int!) {
transactions(
where: {
or: [
{ sender: $address }
{ receiver: $address }
]
}
limit: $limit
orderBy: timestamp
orderDirection: desc
) {
hash
sender
receiver
amount
denom
timestamp
blockHeight
success
}
}
```
### Query Validators
```graphql
query GetValidators {
validators {
address
moniker
votingPower
commission
jailed
uptime
}
}
```
### Query Scry Bindings
```graphql
query GetScryBindings($path: String!) {
scryBindings(where: { path: $path }) {
path
hash
blockHeight
timestamp
signatures {
signer
signature
}
}
}
```
### Query Treasury Claims
```graphql
query GetClaims($address: String!) {
treasuryClaims(where: { claimer: $address }) {
claimer
amount
denom
timestamp
blockHeight
transactionHash
}
}
```
## REST API
The Zenith Watcher also provides REST API endpoints for querying scry oracle data.
### 1. Get Binding by Path
The `/laconic/scryoracle/v1/binding_by_path` API retrieves the binding (hash, block number, and block hash) for a specific path.
**Example:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/binding_by_path?path=/~zod/group-store/groups/random-group/json" | jq
```
**Response:**
```json
{
"binding": {
"hash": "d5af5fddee9de5cedbe1ad1df367f96f67347f8edaddef75",
"block_number": "23",
"block_hash": "a9521112d4ee58da8221c893c8dae465b236456c4becc25edffe85ae3b0ac15e"
},
"binding_with_verification": null
}
```
**With include_verification_data parameter:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/binding_by_path?path=/~zod/group-store/groups/random-group/json&include_verification_data=true" | jq
```
**Parameters:**
- `path` (required): The exact path to lookup
- `include_verification_data` (optional): Whether to return signature and life (default: false)
### 2. Get Bindings by Path Prefix
The `/laconic/scryoracle/v1/bindings_by_prefix` API gets path-to-hash mappings using a path prefix with support for both cursor-based and offset-based pagination.
#### Cursor-based Pagination
**Example - First page:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/bindings_by_prefix?path_prefix=/~zod&pagination.limit=3" | jq
```
**Response:**
```json
{
"path_bindings": {
"/~zod/group-store/groups/random-group/json": {
"hash": "d5af5fddee9de5cedbe1ad1df367f96f67347f8edaddef75",
"block_number": "23",
"block_hash": "a9521112d4ee58da8221c893c8dae465b236456c4becc25edffe85ae3b0ac15e"
},
"/~zod/group-store/members/random-group/json": {
"hash": "77873b7b96bd7f4d5bddff366ba6f6779738edad1fddef75",
"block_number": "23",
"block_hash": "a9521112d4ee58da8221c893c8dae465b236456c4becc25edffe85ae3b0ac15e"
},
"/~zod/metadata-store/associations/groups/random-group/json": {
"hash": "73b7b96bd77a6f47f5ddff367786b57366f97bd7f8edad37",
"block_number": "23",
"block_hash": "a9521112d4ee58da8221c893c8dae465b236456c4becc25edffe85ae3b0ac15e"
}
},
"pagination": {
"next_key": "eyJwYWdpbmF0aW9uX3NraXAiOjN9",
"total": "0"
}
}
```
!!! note "Using next_key"
Use `next_key` from pagination output of the above API response in a subsequent request (as `pagination.key`) to get the next page of results.
**Example - Next page using next_key:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/bindings_by_prefix?path_prefix=/~zod&pagination.key=eyJwYWdpbmF0aW9uX3NraXAiOjN9" | jq
```
#### Offset-based Pagination
**Example:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/bindings_by_prefix?path_prefix=/~zod&pagination.limit=10&pagination.offset=2&pagination.count_total=true" | jq
```
**Parameters:**
- `path_prefix` (required): The path prefix to match against
- `pagination.limit` (optional): Number of results per page (default: 100)
- `pagination.key` (optional): Base64-encoded cursor for next page
- `pagination.offset` (optional): Offset for traditional pagination (cannot be used with key)
- `pagination.count_total` (optional): Whether to return total count (default: false)
- `include_verification_data` (optional): Whether to return signature and life (default: false)
!!! warning "Pagination Note"
You cannot use both `pagination.key` and `pagination.offset` in the same request.
### 3. Get Bindings by Block Number
The `/laconic/scryoracle/v1/bindings_by_block_number` API gets path-to-hash mappings added at a specific block number.
**Example:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/bindings_by_block_number?block_number=25&path_prefix=/~zod" | jq
```
**Response:**
```json
{
"path_bindings": {
"/~zod/publish/comments/2025.3.6..15.30.20..0000/json": {
"hash": "6b477973b7fdd5ee9be367f76fd6b577cd9cd1fe3b7b9dda",
"block_number": "25",
"block_hash": "5a932989009ea3ed054e8a98752eea09384e3bf134ebeb833984f11e52ea8bf5"
},
"/~zod/publish/posts/2025.3.6..15.30.20..0000/json": {
"hash": "ddff757786bb6f4d9ce9ee5af5ff376f57397746b8ef67ba",
"block_number": "25",
"block_hash": "5a932989009ea3ed054e8a98752eea09384e3bf134ebeb833984f11e52ea8bf5"
}
}
}
```
**Parameters:**
- `block_number` (required): The block number to query
- `path_prefix` (optional): Filter results by path prefix
- `include_verification_data` (optional): Whether to return signature and life (default: false)
### 4. Get Bindings in Block Range
The `/laconic/scryoracle/v1/bindings_in_block_range` API gets path-to-hash mappings added within a block range.
**Example:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/bindings_in_block_range?from_block=10&to_block=100&path_prefix=/~zod/publish" | jq
```
**Response:**
```json
{
"path_bindings": {
"/~zod/publish/comments/2025.3.6..15.30.20..0000/json": {
"hash": "6b477973b7fdd5ee9be367f76fd6b577cd9cd1fe3b7b9dda",
"block_number": "25",
"block_hash": "5a932989009ea3ed054e8a98752eea09384e3bf134ebeb833984f11e52ea8bf5"
},
"/~zod/publish/posts/2025.3.6..15.30.20..0000/json": {
"hash": "ddff757786bb6f4d9ce9ee5af5ff376f57397746b8ef67ba",
"block_number": "25",
"block_hash": "5a932989009ea3ed054e8a98752eea09384e3bf134ebeb833984f11e52ea8bf5"
}
}
}
```
**Parameters:**
- `from_block` (required): Starting block number (inclusive)
- `to_block` (required): Ending block number (inclusive)
- `path_prefix` (optional): Filter results by path prefix
- `include_verification_data` (optional): Whether to return signature and life (default: false)
!!! note "Block Range Limit"
The block range is limited to 1000 blocks maximum.
### 5. Get Bindings by Wildcard Pattern
The `/laconic/scryoracle/v1/bindings_by_wildcard` API gets path-to-hash mappings using wildcard pattern matching with support for both cursor-based and offset-based pagination.
**Example - Match any path between ~zod and random-group/json:**
```bash
curl -X 'GET' -H 'accept: application/json' \
"http://127.0.0.1:3008/rest/laconic/scryoracle/v1/bindings_by_wildcard?path_pattern=/~zod/*/random-group/json" | jq
```
**Response:**
```json
{
"path_bindings": {
"/~zod/group-store/groups/random-group/json": {
"hash": "d5af5fddee9de5cedbe1ad1df367f96f67347f8edaddef75",
"block_number": "23",
"block_hash": "a9521112d4ee58da8221c893c8dae465b236456c4becc25edffe85ae3b0ac15e"
},
"/~zod/group-store/members/random-group/json": {
"hash": "77873b7b96bd7f4d5bddff366ba6f6779738edad1fddef75",
"block_number": "23",
"block_hash": "a9521112d4ee58da8221c893c8dae465b236456c4becc25edffe85ae3b0ac15e"
},
"/~zod/metadata-store/associations/groups/random-group/json": {
"hash": "73b7b96bd77a6f47f5ddff367786b57366f97bd7f8edad37",
"block_number": "23",
"block_hash": "a9521112d4ee58da8221c893c8dae465b236456c4becc25edffe85ae3b0ac15e"
}
},
"pagination": {
"next_key": null,
"total": "0"
}
}
```
**Parameters:**
- `path_pattern` (required): The wildcard pattern to match (use `*` for wildcard matching)
- `pagination.limit` (optional): Number of results per page (default: 100)
- `pagination.key` (optional): Base64-encoded cursor for next page
- `pagination.offset` (optional): Offset for traditional pagination (cannot be used with key)
- `pagination.count_total` (optional): Whether to return total count (default: false)
- `include_verification_data` (optional): Whether to return signature and life (default: false)
!!! warning "Pagination Note"
You cannot use both `pagination.key` and `pagination.offset` in the same request.
## Using the APIs
### With curl (GraphQL)
```bash
# Query Zenith Watcher
curl -X POST https://zenith-watcher.zenith-test.tlon.systems/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "query { validators { moniker votingPower jailed } }"
}'
```
### With JavaScript/TypeScript (GraphQL)
```javascript
const query = `
query GetAccount($address: String!) {
account(address: $address) {
balances {
denom
amount
}
}
}
`;
const variables = { address: "zenith1..." };
const response = await fetch('https://zenith-watcher.zenith-test.tlon.systems/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query, variables })
});
const data = await response.json();
```
### With GraphQL Client Libraries
```javascript
import { GraphQLClient } from 'graphql-request';
const client = new GraphQLClient(
'https://zenith-watcher.zenith-test.tlon.systems/graphql'
);
const query = `
query GetAccount($address: String!) {
account(address: $address) {
balances { denom amount }
}
}
`;
const data = await client.request(query, { address: 'zenith1...' });
```
## Rate Limiting and Best Practices
- **Rate Limits**: Public watcher endpoints have rate limiting in place. For production applications, consider running your own watcher instances.
- **Pagination**: Use pagination parameters for queries that return large result sets.
- **Caching**: Cache frequently accessed data to reduce API load.
- **Error Handling**: Implement proper error handling and retry logic for network failures.
!!! note "Watcher Documentation"
For more information about the watcher architecture and deployment, see the [Watchers documentation](../documentation/watchers.md).
docs/api/zenithd.md
+139
View File
@@ -0,0 +1,139 @@
# zenithd API
The zenithd node exposes REST API endpoints for querying blockchain state and network information. By default, the API server runs on port 1317, with Tendermint RPC on port 26657.
## Node and Network Information
```bash
# Get node status
curl http://localhost:26657/status
# Get node info
curl http://localhost:26657/node_info
# Get blockchain info
curl http://localhost:26657/blockchain
# Get latest block
curl http://localhost:26657/block
```
## Account and Balance Queries
```bash
# Query account information
curl http://localhost:1317/cosmos/auth/v1beta1/accounts/zenith1...
# Query account balances
curl http://localhost:1317/cosmos/bank/v1beta1/balances/zenith1...
# Query specific denomination balance
curl http://localhost:1317/cosmos/bank/v1beta1/balances/zenith1.../by_denom?denom=znt
```
## Onboarding Module Queries
```bash
# List all participants
curl http://localhost:1317/zenith/onboarding/participants
# Get specific participant
curl http://localhost:1317/zenith/onboarding/participant/zenith1...
```
## Scry Oracle Module Queries
```bash
# Get scry binding by path
curl http://localhost:1317/zenith/scryoracle/bindings?path=/~zen/group-store/groups
# Get bindings by block number
curl http://localhost:1317/zenith/scryoracle/bindings_by_block/100
# Get bindings in block range
curl http://localhost:1317/zenith/scryoracle/bindings_by_range?start=100&end=200
```
## Zenith Module Queries
```bash
# Get ownership by Azimuth point ID
curl http://localhost:1317/zenith/zenith/ownership/123
# Get balances by point
curl http://localhost:1317/zenith/zenith/balances_by_point/123
# Get current Ethereum height
curl http://localhost:1317/zenith/zenith/eth_height
# Get module parameters
curl http://localhost:1317/zenith/zenith/params
```
## Treasury Module Queries
```bash
# Get distribution info
curl http://localhost:1317/zenith/immutabletreasury/distribution/participant-id
# Get claimable tokens
curl http://localhost:1317/zenith/immutabletreasury/claimable/zenith1...
# Get block rewards state
curl http://localhost:1317/zenith/immutabletreasury/block_rewards
```
## Validator and Staking Queries
```bash
# List all validators
curl http://localhost:1317/cosmos/staking/v1beta1/validators
# Get specific validator
curl http://localhost:1317/cosmos/staking/v1beta1/validators/zenithvaloper1...
# Get delegations for an address
curl http://localhost:1317/cosmos/staking/v1beta1/delegations/zenith1...
```
## Using with Remote Nodes
```bash
# Query testnet node
curl https://zenithd.zenith-test.tlon.systems/status
# Query account balance on testnet
curl https://zenithd.zenith-test.tlon.systems/cosmos/bank/v1beta1/balances/zenith1...
# Query participants on testnet
curl https://zenithd.zenith-test.tlon.systems/zenith/onboarding/participants
```
## Formatted Output with jq
```bash
# Pretty print node status
curl -s http://localhost:26657/status | jq
# Extract specific fields
curl -s http://localhost:26657/status | jq '.result.sync_info'
# Get latest block height
curl -s http://localhost:26657/status | jq '.result.sync_info.latest_block_height'
# Format account balances
curl -s http://localhost:1317/cosmos/bank/v1beta1/balances/zenith1... | jq '.balances'
```
## Pagination Examples
```bash
# Get validators with pagination
curl "http://localhost:1317/cosmos/staking/v1beta1/validators?pagination.limit=10&pagination.offset=0"
# Get next page of validators
curl "http://localhost:1317/cosmos/staking/v1beta1/validators?pagination.limit=10&pagination.offset=10"
# Get all balances with pagination
curl "http://localhost:1317/cosmos/bank/v1beta1/balances/zenith1...?pagination.limit=100"
```