commit 00424e7cdae92ef6068c62cb3ef9f0bc39b2e3f5 Author: zramsay Date: Thu Nov 6 18:34:15 2025 +0000 docs mvp diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..3c20ba1 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,22 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version, and other tools you might need +build: + os: ubuntu-24.04 + tools: + # Specify the language and version your project requires, + # by uncommenting one of the following tools. + # + python: "3.13" + # ruby: "3.3" + # nodejs: "22" + # rust: "1.82" + # golang: "1.23" + + commands: + - pip install mkdocs + - mkdocs build --site-dir $READTHEDOCS_OUTPUT/html diff --git a/README.md b/README.md new file mode 100644 index 0000000..bcf1774 --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# Zenith Documentation + +Official documentation for the Zenith blockchain ecosystem, built with MkDocs and hosted on ReadTheDocs. + +## Development Setup + +### Prerequisites +- Python 3.8+ +- pip + +### Local Development + +1. **Install dependencies**: + ```bash + pip install -r requirements.txt + ``` + +2. **Serve locally**: + ```bash + mkdocs serve + ``` + Visit `http://localhost:8000` to view the documentation. + +3. **Build static site**: + ```bash + mkdocs build + ``` + +## Content Structure + +- `docs/overview/` - Introduction and key concepts +- `docs/documentation/` - Technical documentation +- `docs/tokenomics/` - Token economy and distribution +- `docs/command-reference/` - CLI command references +- `docs/public-infrastructure.md` - Public infrastructure details + +## Contributing + +1. Edit markdown files in the `docs/` directory +2. Test locally with `mkdocs serve` +3. Submit pull requests with changes + +## Deployment + +Documentation is automatically deployed to ReadTheDocs when changes are pushed to the main branch. + +### Manual Deployment + +For testing deployment: +```bash +mkdocs gh-deploy +``` + +## Configuration + +The site configuration is in `mkdocs.yml`: +- Navigation structure +- Theme settings (Material Design) +- Plugins and extensions +- Site metadata \ No newline at end of file diff --git a/docs/api/azimuth-watcher.md b/docs/api/azimuth-watcher.md new file mode 100644 index 0000000..694db37 --- /dev/null +++ b/docs/api/azimuth-watcher.md @@ -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). diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..8862f56 --- /dev/null +++ b/docs/api/index.md @@ -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. diff --git a/docs/api/janus.md b/docs/api/janus.md new file mode 100644 index 0000000..552bac7 --- /dev/null +++ b/docs/api/janus.md @@ -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 diff --git a/docs/api/lockdrop-watcher.md b/docs/api/lockdrop-watcher.md new file mode 100644 index 0000000..2dd0897 --- /dev/null +++ b/docs/api/lockdrop-watcher.md @@ -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). diff --git a/docs/api/zenith-desk-api.md b/docs/api/zenith-desk-api.md new file mode 100644 index 0000000..16f9159 --- /dev/null +++ b/docs/api/zenith-desk-api.md @@ -0,0 +1,1202 @@ +# Zenith Developer API Documentation + +This document provides comprehensive documentation for developers who want to use the %zenith agent or library to access the Zenith blockchain in their own applications. + +## Pokes (Agent Interactions) + +### Configuration Pokes + +#### `%config-zenith-host` + +**Purpose**: Sets the hostname or IP address for the Zenith blockchain node (zenithd). + +**Input Type**: `@t` (cord/text string) + +**Output**: Updates the agent's configuration state. No return value. + +**Default**: `'localhost'` + +**Description**: +Configures the hostname or IP address where your zenithd instance is running, whether standalone or as part of a Laconic stack. This setting is used in combination with the port configuration pokes to build complete endpoint URLs for accessing the Zenith blockchain APIs. + +If an invalid or unreachable host is set, the agent's healthchecks will fail and connection status will be `%.n` (false). + +**Examples**: + +Dojo command: +``` +:zenith &config-zenith-host 'mynode.example.com' +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-zenith-host !>('192.168.1.100')] +``` + +#### `%config-rpc-port` + +**Purpose**: Sets the port number for the CometBFT RPC endpoint. + +**Input Type**: `@t` (cord/text string) + +**Output**: Updates the agent's configuration state. No return value. + +**Default**: `'26657'` (standard CometBFT RPC port) + +**Description**: +Configures the port number for consensus layer communication with the CometBFT node. This is used in combination with the zenith-host setting to form complete RPC endpoint URLs. The port accepts any cord value without validation. + +The RPC endpoint provides access to CometBFT's consensus and blockchain query APIs. See the [CometBFT RPC documentation](https://docs.cometbft.com/main/rpc/#/) for available endpoints. Note that while CometBFT documentation shows endpoints starting with `/v1`, zenithd exposes this API without that prefix. + +**Examples**: + +Dojo command: +``` +:zenith &config-rpc-port '26657' +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-rpc-port !>('8545')] +``` + +#### `%config-http-api-port` + +**Purpose**: Sets the port number for the Zenith HTTP REST API endpoint. + +**Input Type**: `@t` (cord/text string) + +**Output**: Updates the agent's configuration state. No return value. + +**Default**: `'1317'` (standard Cosmos SDK REST API port) + +**Description**: +Configures the port number for accessing Zenith's extended REST API. This is used in combination with the zenith-host setting to form complete HTTP API endpoint URLs. The API provides access to module state queries, balance information, treasury operations, oracle queries, and some specific transaction types (like token claiming). + +The REST API has been significantly extended beyond the standard Cosmos SDK to include Zenith-specific functionality like scry oracle queries, Azimuth point lookups, and treasury operations. + +**Examples**: + +Dojo command: +``` +:zenith &config-http-api-port '1317' +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-http-api-port !>('8080')] +``` + +#### `%config-oracle-port` + +**Purpose**: Sets the port number for the Zenith scryoracle long polling endpoint. + +**Input Type**: `@t` (cord/text string) + +**Output**: Updates the agent's configuration state. No return value. + +**Default**: `'9473'` (zenithd-specific port) + +**Description**: +Configures the port number for accessing Zenith's scryoracle subscription service. This endpoint provides a long polling API at `/api/scrybindings/poll` that returns new scry bindings as they are added to the blockchain. The %zenith agent uses this endpoint to watch for new scry bindings and provide them to client applications through oracle subscriptions. + +The long polling endpoint responds with mappings from block numbers to scry bindings (path→hash mappings), enabling real-time notifications when new data is canonicalized on the Scry Oracle. + +**Examples**: + +Dojo command: +``` +:zenith &config-oracle-port '9473' +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-oracle-port !>('9000')] +``` + +#### `%config-rpc` + +**Purpose**: Sets both the hostname and RPC port for the CometBFT endpoint in a single poke. + +**Input Type**: `[zenith-host=@t rpc-port=@t]` (cell of two cords) + +**Output**: Updates both zenith-host and rpc-port in the agent's configuration state. No return value. + +**Description**: +Convenience poke that combines `%config-zenith-host` and `%config-rpc-port` functionality. Sets both the hostname/IP and port number for consensus layer communication with the CometBFT node in a single operation. + +**Examples**: + +Dojo command: +``` +:zenith &config-rpc ['mynode.example.com' '26657'] +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-rpc !>(['192.168.1.100' '8545'])] +``` + +#### `%config-http-api` + +**Purpose**: Sets both the hostname and HTTP API port for the Zenith REST API endpoint in a single poke. + +**Input Type**: `[zenith-host=@t http-api-port=@t]` (cell of two cords) + +**Output**: Updates both zenith-host and http-api-port in the agent's configuration state. No return value. + +**Description**: +Convenience poke that combines `%config-zenith-host` and `%config-http-api-port` functionality. Sets both the hostname/IP and port number for accessing Zenith's extended REST API in a single operation. + +**Examples**: + +Dojo command: +``` +:zenith &config-http-api ['mynode.example.com' '1317'] +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-http-api !>(['192.168.1.100' '8080'])] +``` + +#### `%config-chain-id` + +**Purpose**: Sets the chain ID for the Zenith blockchain. + +**Input Type**: `@t` (cord/text string) + +**Output**: Updates the chain-id in the agent's configuration state. No return value. + +**Default**: `'zenith-localtestnet'` + +**Description**: +Configures the chain ID that must match the chain ID of the zenithd instance you're connecting to. This is critical for transaction signing - transactions cannot be properly signed without using the correct chain ID of the target chain. + +Common chain IDs include: +- `'zenith-localtestnet'` - Local development +- `'zenith-testnet-stage0'` - Testnet stage 0 +- `'zenith-mainnet-stage1'` - Mainnet stage 1 + +**Examples**: + +Dojo command: +``` +:zenith &config-chain-id 'zenith-mainnet-stage1' +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-chain-id !>('zenith-testnet-stage0')] +``` + +#### `%config-janus-endpoint` + +**Purpose**: Sets the Janus endpoint URL for transaction and scry binding submission. + +**Input Type**: `@t` (cord/text string) + +**Output**: Updates the janus-endpoint in the agent's configuration state. No return value. + +**Default**: `'http://localhost:8090'` + +**Description**: +Configures the endpoint URL for the Janus service, which handles transaction and scry binding aggregation between Urbit ships and the Zenith blockchain. Janus is operated by Star nodes and serves as an intermediary that bundles transactions from all ships (Galaxies, Stars, and Planets) before submitting them to Galaxy zenithd nodes for block creation. + +In the Zenith architecture, all transactions flow: Any Ship → Star Janus → zenithd (on Galaxy). Every ship, regardless of type, must send their transactions to a Star running Janus to get them bundled and submitted to their sponsoring galaxy's zenithd for inclusion in blocks. + +**Examples**: + +Dojo command: +``` +:zenith &config-janus-endpoint 'http://mystar.example.com:8090' +``` + +Card for use in other agents: +```hoon +[%pass /config %agent [our.bowl %zenith] %poke %config-janus-endpoint !>('http://192.168.1.100:8080')] +``` + +### Account Management Pokes + +#### `%add-account` + +**Purpose**: Creates a new account from a private key and stores it in the agent. + +**Input Type**: `[name=acc-name priv-key=@ux]` (cell of account name and hexadecimal private key) + +**Output**: Adds the account to the agent's accounts map. No return value. + +**Description**: +Creates a new blockchain account by deriving the public key and Zenith address from the provided secp256k1 private key. The account name can be either `~` (null) for a default account, or a cord (text string) for a named account. If an account with the same name already exists, it will be overwritten. + +**Security Warning**: This is a temporary system for testing only. Private keys stored this way can be easily accessed by malicious Urbit applications with knowledge of the %zenith agent. Do not use this with real funds or important keys. + +The private key must be provided as a hexadecimal atom (`@ux`) with dots separating groups for valid Hoon syntax. + +**Examples**: + +Dojo command (default account): +``` +:zenith &add-account [~ 0xb9e6.9d23.a396.4287.63c1.220b.f46d.936b.bd00.52e2.a124.ac0b.e2d6.237d.5c6b.e8ed] +``` + +Dojo command (named account): +``` +:zenith &add-account ['alice' 0xb9e6.9d23.a396.4287.63c1.220b.f46d.936b.bd00.52e2.a124.ac0b.e2d6.237d.5c6b.e8ed] +``` + +Card for use in other agents: +```hoon +[%pass /account %agent [our.bowl %zenith] %poke %add-account !>(['myaccount' 0x1234.5678.9abc.def0.1234.5678.9abc.def0.1234.5678.9abc.def0.1234.5678.9abc.def0])] +``` + +#### `%update-account` + +**Purpose**: Updates the Cosmos SDK account number and sequence number for an existing account. + +**Input Type**: `[name=acc-name acc-num=@ud seq-num=@ud]` (account name, account number, sequence number) + +**Output**: Updates the account in the accounts map if it exists. No return value. + +**Description**: +Updates %zenith's internal record of the Cosmos SDK account number and sequence number for an existing account. This only affects the locally stored values and is useful for tracking what happened during transaction processing, but doesn't actually affect transaction signing behavior. + +**For Informational Purposes Only**: This poke is called automatically by the %zenith agent during transaction processing. Developers should not use this poke manually, as any values set here will be overwritten with fresh values from the blockchain before they are used for transaction signing. + +#### `%delete-account` + +**Purpose**: Removes an account from the agent's storage. + +**Input Type**: `acc-name` (account name - either `~` for default account or a cord for named account) + +**Output**: Removes the account from the accounts map. No return value. + +**Description**: +Completely removes an account and its associated private key, public key, and address information from the %zenith agent's storage. This action is irreversible - if you delete an account, you'll need to re-add it with `%add-account` to use it again. + +The operation silently succeeds even if the specified account doesn't exist. + +**Examples**: + +Dojo command (delete default account): +``` +:zenith &delete-account ~ +``` + +Dojo command (delete named account): +``` +:zenith &delete-account 'alice' +``` + +Card for use in other agents: +```hoon +[%pass /cleanup %agent [our.bowl %zenith] %poke %delete-account !>('testaccount')] +``` + +### Blockchain Interaction Pokes + +#### `%post-scry-binding` + +**Purpose**: Submits a scry binding to the Scry Oracle for canonicalization on the blockchain. + +**Input Type**: `[pat=path hash=@t]` (scry path and content hash) + +**Output**: Adds the binding to pending-bindings for submission to the blockchain. No return value. + +**Description**: +This is the primary method for developers to canonicalize data on the Scry Oracle. The poke accepts a scry path and the hash of the data at that path, adding it to the agent's pending bindings which are exposed via the `/zenith/scry-bindings` HTTP endpoint for zenithd to query and include in future blocks. + +The scry path must be non-empty and start with a valid Urbit ship (@p). Remote scry paths typically follow the format `/~ship/g/x/1/app-name//1/resource`. The hash should be a cord representing 32 bytes in hexadecimal format (e.g., 'd3bb0d59e354ea843e790801303a46e880219996c6850ddd4c85a83e08c41d92'), typically generated using the `hash-noun-to-cord` function from the zenith library. + +**Future Architecture**: In upcoming versions, this will transition to submitting scry bindings through Janus (operated by Stars) rather than the direct HTTP endpoint system. + +**Examples**: + +Dojo command: +``` +:zenith &post-scry-binding [/~zod/g/x/1/my-app//1/posts/latest/json 'd3bb0d59e354ea843e790801303a46e880219996c6850ddd4c85a83e08c41d92'] +``` + +Card for use in other agents: +```hoon +[%pass /scry %agent [our.bowl %zenith] %poke %post-scry-binding !>([/~our/g/x/1/my-app//1/data/json 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'])] +``` + +#### `%listen-oracle` + +**Purpose**: Subscribe to oracle updates for scry bindings matching a specific path prefix. + +**Input Type**: `[prefix=path from=(unit @ud)]` (path prefix and optional starting block number) + +**Output**: Sets up subscription and begins polling for new bindings. Returns cards for oracle polling. + +**Description**: +Establishes a subscription to receive new scry bindings that match the specified path prefix. This poke must be paired with a watch on the corresponding `/oracle/[prefix]` path to actually receive updates. + +If a starting block number (`from`) is provided, the subscription will begin from that block. If `~` (null) is provided, it will start from the current block height. + +If %zenith is already polling that path prefix, the poke will be ignored, but the subscription will still succeed and the subscriber will receive updates along with other subscribers. + +**Examples**: + +Card for use in other agents (must include both poke and watch): +```hoon +:~ [%pass /listen %agent [our.bowl %zenith] %poke %listen-oracle !>([/~zod/my-app ~])] + [%pass /oracle/updates %agent [our.bowl %zenith] %watch [%oracle /~zod/my-app]] +== +``` + +## Scries (Data Queries) + +### Configuration and Status Scries + +#### `/x/config` + +**Purpose**: Retrieves the current agent configuration. + +**Input**: None + +**Output**: `config` structure with the following fields: +- `rpc-endpoint=@t` - Complete RPC endpoint URL +- `http-api-endpoint=@t` - Complete HTTP API endpoint URL +- `bindings-endpoint=@t` - Complete oracle endpoint URL +- `zenith-host=@t` - Configured hostname +- `rpc-port=@t` - RPC port +- `http-api-port=@t` - HTTP API port +- `bindings-port=@t` - Oracle port +- `chain-id=@t` - Blockchain chain ID +- `janus-endpoint=@t` - Janus endpoint URL + +**Description**: +Returns the complete configuration structure including both individual settings and computed endpoint URLs formed by combining host and port values. + +**Examples**: + +Dojo command: +``` +.^(config %gx /=zenith=/config/noun) +``` + +From other agents: +```hoon +.^ config + %gx + (scot %p our.bowl) + %zenith + (scot %da now.bowl) + /config/noun +== +``` + +#### `/x/account/[name]` + +**Purpose**: Retrieves information for a specific account. + +**Input**: Account name in the path (`~` encoded as empty string for default account, or a cord for named accounts) + +**Output**: `(unit account)` - Either `~` if account doesn't exist, or `[~ u=account]` where account structure contains: +- `addr=@t` - Zenith blockchain address +- `pub-key=@ux` - Public key +- `priv-key=@ux` - Private key (security warning applies) +- `acc-num=@ud` - Cosmos SDK account number +- `seq-num=@ud` - Cosmos SDK sequence number + +**Description**: +Returns the complete account information for the specified account name. Returns `~` if the account doesn't exist, or `[~ u=account]` if it exists. To access fields from the response, use wings like `addr.u.res` where `res` is the response. + +The private key is included in the response, so the same security warnings about private key storage apply. + +**Examples**: + +Dojo command (default account, ~ encoded as empty string): +``` +.^((unit account) %gx /=zenith=/account//noun) +``` + +Dojo command (named account): +``` +.^((unit account) %gx /=zenith=/account/alice/noun) +``` + +From other agents: +```hoon +.^ (unit account) + %gx + (scot %p our.bowl) + %zenith + (scot %da now.bowl) + /account/alice/noun +== +``` + +#### `/x/rpc-connected` + +**Purpose**: Checks if the RPC connection is active. + +**Output**: `[connected=?]` - Boolean indicating RPC connection status + +**Examples**: +``` +.^([connected=?] %gx /=zenith=/rpc-connected/noun) +``` + +#### `/x/http-api-connected` + +**Purpose**: Checks if the HTTP API connection is active. + +**Output**: `[connected=?]` - Boolean indicating HTTP API connection status + +**Examples**: +``` +.^([connected=?] %gx /=zenith=/http-api-connected/noun) +``` + +#### `/x/oracle-connected` + +**Purpose**: Checks if the oracle connection is active. + +**Output**: `[connected=?]` - Boolean indicating oracle connection status + +**Examples**: +``` +.^([connected=?] %gx /=zenith=/oracle-connected/noun) +``` + +#### `/x/connected` + +**Purpose**: Checks if all connections (RPC, HTTP API, and oracle) are active. + +**Output**: `[connected=?]` - Boolean indicating overall connection status (true only if all connections are active) + +**Examples**: +``` +.^([connected=?] %gx /=zenith=/connected/noun) +``` + +#### `/x/latest-block-height` + +**Purpose**: Retrieves the latest known block height. + +**Output**: `@ud` - Latest block height as recorded by the healthcheck system + +**Description**: +Returns the latest block height that the agent has observed through its healthcheck polling. This value is updated regularly during healthcheck operations. + +**Examples**: +``` +.^(@ud %gx /=zenith=/latest-block-height/noun) +``` + +## Subscriptions + +### `/oracle/[prefix]` + +**Purpose**: Subscribe to receive new scry bindings for a specific path prefix. + +**Input**: Path prefix in the subscription path + +**Output**: Receives `%scry-bindings` facts containing new scry bindings as they are discovered + +**Description**: +Subscribes to oracle updates for the specified path prefix. When new scry bindings matching the prefix are discovered, they will be sent as `%scry-bindings` facts containing a `scry-bindings` map (path→hash mappings). + +This subscription must be paired with a `%listen-oracle` poke to establish the polling mechanism. The agent will continuously monitor for new bindings and broadcast them to all subscribers of the matching prefix. + +**Examples**: + +From other agents: +```hoon +[%pass /oracle/updates %agent [our.bowl %zenith] %watch [%oracle /~zod/my-app]] +``` + +Complete setup (poke + watch): +```hoon +:~ [%pass /listen %agent [our.bowl %zenith] %poke %listen-oracle !>([/~zod/my-app ~])] + [%pass /oracle/updates %agent [our.bowl %zenith] %watch [%oracle /~zod/my-app]] +== +``` + +**Fact Processing**: +```hoon +++ on-agent + |= [=wire =sign:agent:gall] + ^- (quip card _this) + ?+ wire (on-agent:def wire sign) + [%oracle %updates ~] + ?+ -.sign (on-agent:def wire sign) + %fact + ?+ p.cage.sign (on-agent:def wire sign) + %scry-bindings + =/ bindings !<(scry-bindings q.cage.sign) + :: Process new bindings here + `this + == + == + == +``` + +## Threads + +Threads provide specific operations that can be called via the Spider agent or %khan vane. Threads can also be run manually from the dojo through convenience pokes in the %zenith agent. + +### Account and Balance Operations + +#### `get-zenith-address` + +**Purpose**: Retrieves the Zenith blockchain address for a given Urbit ship. + +**Input**: `ship` - Urbit ship (@p) + +**Output**: `@t` - Zenith address + +**Description**: +Queries the Zenith HTTP API endpoint `/laconic/zenith/v1/address_by_point` to get the blockchain address associated with an Urbit ship. This uses the configured HTTP API endpoint from the %zenith agent. + +**Examples**: + +Via %zenith poke: +``` +:zenith &zenith-address ~bitnet +``` + +Using %khan vane: +```hoon +[%pass /zenith-addr %arvo %k %fard %zenith %get-zenith-address %noun !>(~bitnet)] +``` + +Using %spider agent: +```hoon +[%pass /zenith-addr %agent [our.bowl %spider] %poke %spider-start !>([~ ``@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl))) byk.bowl(r da+now.bowl) %get-zenith-address !>(~bitnet)])] +``` + +Thread name and vase for other uses: +```hoon +[%get-zenith-address !>(~bitnet)] +``` + +#### `get-balances-by-ship` + +**Purpose**: Retrieves token balances for a given Urbit ship. + +**Input**: `ship` - Urbit ship (@p) + +**Output**: `balances` - List of `[denom=@t amount=@ud]` balance entries + +**Description**: +Queries the Zenith HTTP API endpoint `/laconic/zenith/v1/balances_by_point` to get all token balances for the Zenith address associated with an Urbit ship. + +**Examples**: + +Via %zenith poke: +``` +:zenith &balances-by-ship ~bitnet +``` + +Using %khan vane: +```hoon +[%pass /balances %arvo %k %fard %zenith %get-balances-by-ship %noun !>(~bitnet)] +``` + +Thread name and vase for other uses: +```hoon +[%get-balances-by-ship !>(~bitnet)] +``` + +#### `get-balances-by-addr` + +**Purpose**: Retrieves token balances for a given Zenith address. + +**Input**: `@t` - Zenith address as a cord + +**Output**: `balances` - List of `[denom=@t amount=@ud]` balance entries + +**Description**: +Queries the standard Cosmos bank module endpoint `/cosmos/bank/v1beta1/balances/[address]` to get all token balances for the specified Zenith address. + +**Examples**: + +Via %zenith poke: +``` +:zenith &balances-by-addr 'zenith1abc123...' +``` + +Thread name and vase for other uses: +```hoon +[%get-balances-by-addr !>('zenith1abc123...')] +``` + +### Transaction Operations + +#### `send-to-ship` + +**Purpose**: Sends tokens from an account to an Urbit ship's Zenith address. + +**Input**: `[acc-name=acc-name to=@p amount=@ud denom=@t]` - Account name, recipient ship, amount, and denomination + +**Output**: Transaction result + +**Description**: +Sends tokens from the specified account to an Urbit ship by first resolving the ship's Zenith address and then executing the transfer. This thread combines `get-zenith-address` and `send-to-account` operations. + +**Note**: Success of this thread only indicates that the transaction was successfully passed to Janus for bundling, not that it was actually confirmed on-chain. + +**Examples**: + +Via %zenith poke: +``` +:zenith &send-to-ship [~ ~bitnet 1.000.000 'znt'] +``` + +Thread name and vase for other uses: +```hoon +[%send-to-ship !>([~ ~bitnet 1.000.000 'znt'])] +``` + +#### `send-to-addr` + +**Purpose**: Sends tokens from an account to a Zenith address. + +**Input**: `[acc-name=acc-name to=@t amount=@ud denom=@t]` - Account name, recipient address, amount, and denomination + +**Output**: Transaction result message from Janus + +**Description**: +Sends tokens from the specified account to a Zenith blockchain address. The thread fetches the latest account numbers from the chain, creates a signed transaction, and submits it to Janus for bundling. The account sequence numbers are automatically updated after submission. + +**Note**: Success only indicates the transaction was accepted by Janus for bundling, not on-chain confirmation. + +**Examples**: + +Via %zenith poke: +``` +:zenith &send-to-addr [~ 'zenith1abc123...' 1.000.000 'znt'] +``` + +Thread name and vase for other uses: +```hoon +[%send-to-addr !>([~ 'zenith1abc123...' 1.000.000 'znt'])] +``` + +### Oracle Operations + +#### `get-scry-bindings` + +**Purpose**: Retrieves multiple scry bindings matching a path prefix with pagination support. + +**Input**: `query:oracle` - Query structure with prefix and pagination parameters + +**Output**: `response:oracle` - Structure containing: +- `bindings=scry-bindings` - Map of paths to hashes `(map path @t)` +- `page-info=page-info` - Pagination info with: + - `next-key=(unit @t)` - Key for next page (if any) + - `total=@ud` - Total count (always returned due to current zenithd implementation) + +**Description**: +Queries the Zenith HTTP API endpoint `/laconic/scryoracle/v1/bindings_by_prefix` to get scry bindings that match the specified path prefix. Supports pagination with either key-based or offset/limit pagination, and can return results in reverse order. + +**Note**: This thread is designed to support more complex query structures in the future, but currently there's no indexer or functionality built into zenithd that can provide a backend for more advanced query features. + +**Examples**: + +Via %zenith poke: +``` +:zenith &scry-bindings [/~zod [offset=0 limit=10] count-total=%.y reverse=%.n] +``` + +Thread name and vase for other uses: +```hoon +[%get-scry-bindings !>([/~zod [offset=0 limit=10] count-total=%.y reverse=%.n])] +``` + +#### `get-scry-binding` + +**Purpose**: Retrieves the hash for a specific scry path. + +**Input**: `path` - Scry path + +**Output**: `@t` - 32-byte hash value encoded as a hex string + +**Description**: +Queries the Zenith HTTP API endpoint `/laconic/scryoracle/v1/hashes` to get the canonicalized hash for a specific scry path. Returns the hash if the binding exists on the Scry Oracle. + +**Examples**: + +Via %zenith poke: +``` +:zenith &scry-binding /~zod/g/x/1/my-app//1/data/json +``` + +Thread name and vase for other uses: +```hoon +[%get-scry-binding !>(/~zod/g/x/1/my-app//1/data/json)] +``` + +#### `verified-scry` + +**Purpose**: Performs a remote scry and verifies the result against the Scry Oracle. + +**Input**: `remote-scry:oracle` - Structure containing: +- `kind=?(%keen %chum %shut)` - Scry type (unencrypted, two-party, or multi-party encrypted) +- `spar:ames` - Remote scry target (ship and path) +- `timeout=(unit @dr)` - Optional timeout duration (strongly recommended) + +**Output**: `(unit [roar:ames verified=(unit ?)])` - Either `~` if no data, or tuple containing: +- `roar:ames` - The remote scry response +- `verified=(unit ?)` - Verification result: `~` if no oracle hash, `%.y` if verified, `%.n` if hash mismatch + +**Description**: +Performs a remote scry via %ames and simultaneously fetches the expected hash from the Scry Oracle. The thread verifies that the received data matches the canonicalized hash, providing Byzantine fault tolerance for remote scry operations. + +**Important**: If no timeout is provided and the target ship doesn't respond to the remote scry request, the thread will hang indefinitely. A timeout is very strongly recommended. + +**Examples**: + +Via %zenith poke: +``` +:zenith &verified-scry [%keen [~zod /g/x/1/my-app//1/data/json] `~s30] +``` + +Thread name and vase for other uses: +```hoon +[%verified-scry !>([%keen [~zod /g/x/1/my-app//1/data/json] `~s30])] +``` + +#### `verify-scry` + +**Purpose**: Verifies that a provided hash matches the canonical hash in the Scry Oracle. + +**Input**: `[spar:ames hash=@ux]` - Target ship and path, plus hash to verify + +**Output**: `?` - Boolean indicating whether the hash matches the oracle + +**Description**: +Queries the Scry Oracle to get the canonical hash for the specified path and compares it against the provided hash. Returns `%.y` if they match, `%.n` if they don't match or if no oracle hash exists. + +**Examples**: + +Via %zenith poke: +``` +:zenith &verify-scry [[~zod /g/x/1/my-app//1/data/json] 0xd3bb.0d59.e354.ea84.3e79.0801.303a.46e8.8021.9996.c685.0ddd.4c85.a83e.08c4.1d92] +``` + +Thread name and vase for other uses: +```hoon +[%verify-scry !>([[~zod /g/x/1/my-app//1/data/json] 0xd3bb.0d59.e354.ea84.3e79.0801.303a.46e8.8021.9996.c685.0ddd.4c85.a83e.08c4.1d92])] +``` + +### Network and Utility Operations + +#### `get-rpc-status` + +**Purpose**: Retrieves comprehensive status information from the CometBFT RPC endpoint. + +**Input**: None (unit value) + +**Output**: `status` - Structure containing: +- `node-info` - Node protocol version, ID, network info, version, etc. +- `sync-info` - Latest/earliest block info, sync status, block heights and times +- `validator-info` - Validator address, public key, and voting power + +**Description**: +Queries the CometBFT RPC endpoint `/status` to get detailed information about the blockchain node's current state, including sync status, block information, and validator details. + +**Examples**: + +Via %zenith poke: +``` +:zenith &rpc-status ~ +``` + +Thread name and vase for other uses: +```hoon +[%get-rpc-status !>(~)] +``` + +#### `get-eth-height` + +**Purpose**: Retrieves the latest Ethereum block height as seen by the Zenith chain. + +**Input**: None (null value) + +**Output**: `@ud` - Ethereum block height + +**Description**: +Queries the Zenith HTTP API endpoint `/laconic/zenith/v1/eth_height` to get the latest Ethereum block height that the Zenith chain has observed. This is used for cross-chain coordination and monitoring. + +**Examples**: + +Via %zenith poke: +``` +:zenith ð-height ~ +``` + +Thread name and vase for other uses: +```hoon +[%get-eth-height !>(~)] +``` + +#### `get-http-api-request` + +**Purpose**: Makes a generic HTTP GET request to the Zenith HTTP API endpoint. + +**Input**: `tape` - URL path to append to the HTTP API endpoint (must include leading slash) + +**Output**: `json` - Raw JSON response from the API + +**Description**: +Makes a generic HTTP GET request by appending the provided URL path to the configured HTTP API endpoint. This is a utility thread for accessing any HTTP API endpoint that isn't covered by more specific threads. + +The path must include a leading slash (e.g., `"/cosmos/bank/v1beta1/balances/zenith1abc123"`). + +**Examples**: + +Thread name and vase for other uses: +```hoon +[%get-http-api-request !>("/cosmos/bank/v1beta1/balances/zenith1abc123")] +``` + +#### `get-rpc-request` + +**Purpose**: Makes a generic HTTP GET request to the CometBFT RPC endpoint. + +**Input**: `tape` - URL path to append to the RPC endpoint (must include leading slash) + +**Output**: `json` - Raw JSON response from the RPC API + +**Description**: +Makes a generic HTTP GET request by appending the provided URL path to the configured CometBFT RPC endpoint. This is a utility thread for accessing any CometBFT RPC endpoint that isn't covered by more specific threads. + +The path must include a leading slash (e.g., `"/block?height=1000"`). + +**Examples**: + +Thread name and vase for other uses: +```hoon +[%get-rpc-request !>("/block?height=1000")] +``` + +## Library Arms and Types + +The %zenith library provides utility functions that can be imported and used in your own applications. Make sure to include all files in the `zenith-dev` directory in your desk. Import the library with `/+ *zenith` or `/+ zenith` in your Hoon code. + +### Arms + +#### `+gen-account` + +**Purpose**: Generates a complete account structure from a private key. + +**Input**: `@ux` - secp256k1 private key + +**Output**: `account` - Complete account structure with address, keys, and initial sequence numbers + +**Description**: +Creates a complete account by deriving the public key and Zenith address from a secp256k1 private key. The account structure includes the Bech32-encoded Zenith address, compressed public key, private key, and initialized account/sequence numbers (both set to 0). + +**Examples**: +```hoon +=/ priv-key 0xb9e6.9d23.a396.4287.63c1.220b.f46d.936b.bd00.52e2.a124.ac0b.e2d6.237d.5c6b.e8ed +=/ new-account (gen-account:zenith priv-key) +``` + +#### `+pub-to-bech32` + +**Purpose**: Converts a compressed secp256k1 public key to a Zenith Bech32 address. + +**Input**: `@ux` - Compressed secp256k1 public key (33 bytes) + +**Output**: `@t` - Zenith Bech32 address starting with "zenith" + +**Description**: +Converts a compressed public key to a Zenith blockchain address using the Bech32 encoding standard with "zenith" as the human-readable part. The address is derived by taking the RIPEMD160 hash of the SHA256 hash of the public key (Hash160). + +**Examples**: +```hoon +=/ pub-key 0x3.1c17.7888.02b4.50d4.a1aa.a9eb.95c6.dc0f.2c6c.1021.ac53.3b20.d899.0076.ffc7.5582 +=/ address (pub-to-bech32:zenith pub-key) +``` + +#### `+hash-noun` + +**Purpose**: Computes a hash of any Hoon noun. + +**Input**: `*` - Any Hoon noun + +**Output**: `@` - Hash value as an atom + +**Description**: +Computes a hash of a Hoon noun by first jamming it to bytes and then applying SHA256 hash (shax). This is useful for creating content hashes for scry bindings. + +**Examples**: +```hoon +=/ data [%my %sample %data] +=/ data-hash (hash-noun:zenith data) +``` + +#### `+hash-noun-to-cord` + +**Purpose**: Computes a hash of any Hoon noun and returns it as a hexadecimal cord. + +**Input**: `*` - Any Hoon noun + +**Output**: `@t` - Hash value as a 64-character hexadecimal string (32 bytes) + +**Description**: +Combines `hash-noun` with hexadecimal encoding to produce a cord suitable for use with scry binding operations. This is the standard format expected by the Scry Oracle. The output is always exactly 64 characters (32 bytes in hex). + +**Examples**: +```hoon +=/ data [%my %sample %data] +=/ hash-cord (hash-noun-to-cord:zenith data) +:: hash-cord will be something like 'd3bb0d59e354ea843e790801303a46e880219996c6850ddd4c85a83e08c41d92' +``` + +#### `+post-scry-binding` + +**Purpose**: Creates the cards needed to grow a scry endpoint and post its binding to the Scry Oracle. + +**Input**: `[our=ship dap=term now=@da pat=path data=*]` - Ship, app name, current time, path, and data to bind + +**Output**: `(list card:agent:gall)` - List of cards to send + +**Description**: +Convenience function that creates both a %grow card to establish a scry endpoint and a %zenith poke card to submit the scry binding to the oracle. This automates the two-step process of making data available via scry and registering it with the Scry Oracle. + +The function automatically determines the next revision number for the scry path by checking existing scry endpoints, constructs the full scry path in the format `/(scot %p our)/g/x/(scot %ud rev)/[dap]//1/[pat]`, and computes the hash of the data automatically. + +**Examples**: +```hoon +=/ my-data [%posts ~[%latest %announcement]] +=/ cards (post-scry-binding:zenith our.bowl %my-app now.bowl /posts/latest my-data) +:: Send the cards to establish scry endpoint and register with oracle +cards +``` + +### Types + +The %zenith library defines several important types that developers will encounter when working with the Zenith blockchain. Import these types with `/- *zenith` in your Hoon code. + +#### `$config` + +**Description**: Agent configuration structure containing all endpoint and connection settings. + +**Structure**: +```hoon ++$ config + $: rpc-endpoint=@t + http-api-endpoint=@t + bindings-endpoint=@t + zenith-host=@t + rpc-port=@t + http-api-port=@t + bindings-port=@t + chain-id=@t + janus-endpoint=@t + == +``` + +**Fields**: +- `rpc-endpoint` - Complete CometBFT RPC endpoint URL +- `http-api-endpoint` - Complete Zenith HTTP API endpoint URL +- `bindings-endpoint` - Complete oracle polling endpoint URL +- `zenith-host` - Hostname/IP of zenithd instance +- `rpc-port` - CometBFT RPC port +- `http-api-port` - HTTP API port +- `bindings-port` - Oracle polling port +- `chain-id` - Blockchain chain identifier +- `janus-endpoint` - Janus service endpoint URL + +#### `$account` + +**Description**: Blockchain account structure containing keys, address, and sequence information. + +**Structure**: +```hoon ++$ account + $: addr=@t + pub-key=@ux + priv-key=@ux + acc-num=@ud :: index in chain state + seq-num=@ud + == +``` + +**Fields**: +- `addr` - Bech32-encoded Zenith blockchain address (e.g., "zenith1abc123...") +- `pub-key` - Compressed secp256k1 public key (33 bytes) +- `priv-key` - secp256k1 private key (32 bytes) +- `acc-num` - Cosmos SDK account number (index in chain state) +- `seq-num` - Current sequence number for transaction ordering + +**Security Warning**: Private keys stored in this structure can be accessed by any Urbit application with knowledge of the %zenith agent. This is intended for testing only. + +#### `$acc-name` + +**Description**: Account name type used to identify accounts in the %zenith agent. + +**Structure**: +```hoon ++$ acc-name ?(~ @t) +``` + +**Values**: +- `~` - Represents the default account +- `@t` - Named account (any cord/text string) + +**Note**: An empty string `''` is equivalent to `~` and will also point to the default account. + +**Usage**: Used in pokes like `%add-account`, `%delete-account` and threads like `send-to-ship`, `send-to-addr` to specify which account to operate on. + +#### `$balances` + +**Description**: List of token balances for an account. + +**Structure**: +```hoon ++$ balances (list [denom=@t amount=@ud]) +``` + +**Fields**: +- `denom` - Token denomination (e.g., "znt", "$Z", etc.) +- `amount` - Token amount in base units (smallest denomination) + +**Usage**: Returned by balance query threads like `get-balances-by-ship` and `get-balances-by-addr`. + +#### `$scry-bindings` + +**Description**: Map of scry paths to their canonical hashes stored on the Scry Oracle. + +**Structure**: +```hoon ++$ scry-bindings (map path @t) +``` + +**Fields**: +- Key: `path` - Scry path (e.g., `/~zod/g/x/1/my-app//1/data/json`) +- Value: `@t` - 64-character hex string representing the 32-byte hash of the data + +**Usage**: Used in oracle subscriptions, `get-scry-bindings` thread responses, and throughout the Scry Oracle system to represent path→hash mappings. + +#### `$query:oracle` + +**Description**: Query structure for retrieving scry bindings with pagination support. + +**Structure**: +```hoon ++$ query + $: prefix=path + page=page-params + == + ++$ page-params + $: $@(key=@t [offset=@ud limit=@ud]) + count-total=? + reverse=$~(%.n ?) + == +``` + +**Fields**: +- `prefix` - Path prefix to filter scry bindings +- `page` - Pagination parameters: + - Either `key=@t` for key-based pagination, or `[offset=@ud limit=@ud]` for offset-based pagination + - `count-total` - Whether to return total count in response + - `reverse` - Whether to return results in reverse order (defaults to `%.n`) + +**Usage**: Used as input to the `get-scry-bindings` thread to specify which bindings to retrieve and how to paginate results. + +#### `$response:oracle` + +**Description**: Response structure returned by scry binding queries with pagination information. + +**Structure**: +```hoon ++$ response + $: bindings=scry-bindings + page-info=page-info + == + ++$ page-info + $: next-key=(unit @t) + total=@ud + == +``` + +**Fields**: +- `bindings` - Map of scry paths to hashes (see `scry-bindings` type) +- `page-info` - Pagination information: + - `next-key` - Key for next page if more results available, `~` if this is the last page + - `total` - Total count of matching results + +**Usage**: Returned by the `get-scry-bindings` thread to provide both the requested bindings and pagination metadata. + +#### `$remote-scry:oracle` + +**Description**: Input structure for performing verified remote scry operations. + +**Structure**: +```hoon ++$ remote-scry + $: kind=?(%keen %chum %shut) :: unencrypted, two-party, or multi-party encrypted + =spar:ames + timeout=(unit @dr) + == +``` + +**Fields**: +- `kind` - Type of remote scry: + - `%keen` - Unencrypted remote scry (most common) + - `%chum` - Two-party encrypted remote scry + - `%shut` - Multi-party encrypted remote scry +- `spar:ames` - Remote scry target `(pair ship path)` containing target ship and scry path +- `timeout` - Optional timeout duration (strongly recommended to prevent hanging) + +**Usage**: Used as input to the `verified-scry` thread to specify the remote scry operation to perform and verify against the Scry Oracle. + +#### `$status` + +**Description**: Comprehensive status information from the CometBFT RPC endpoint. + +**Structure**: +```hoon ++$ status + $: =node-info + =sync-info + =validator-info + == + ++$ node-info + $: protocol-version=[p2p=@ud block=@ud app=@ud] + id=@t + listen-addr=@t + network=@t + version=@t + channels=@t + moniker=@t + other=[tx-index=@t rpc-address=@t] + == + ++$ sync-info + $: latest-block-hash=@t + latest-app-hash=@t + latest-block-height=@ud + latest-block-time=@t + earliest-block-hash=@t + earliest-app-hash=@t + earliest-block-height=@ud + earliest-block-time=@t + catching-up=? + == + ++$ validator-info + $: address=@t + pub-key=[type=@t value=@t] + voting-power=@t + == +``` + +**Fields**: +- `node-info` - Node protocol version, ID, network info, version, etc. +- `sync-info` - Latest/earliest block info, sync status, block heights and times +- `validator-info` - Validator address, public key, and voting power + +**Usage**: Returned by the `get-rpc-status` thread to provide detailed information about the blockchain node's current state. diff --git a/docs/api/zenith-watcher.md b/docs/api/zenith-watcher.md new file mode 100644 index 0000000..d312224 --- /dev/null +++ b/docs/api/zenith-watcher.md @@ -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). diff --git a/docs/api/zenithd.md b/docs/api/zenithd.md new file mode 100644 index 0000000..a77ede4 --- /dev/null +++ b/docs/api/zenithd.md @@ -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" +``` diff --git a/docs/assets/zenith-logo.png b/docs/assets/zenith-logo.png new file mode 100644 index 0000000..0cdb261 Binary files /dev/null and b/docs/assets/zenith-logo.png differ diff --git a/docs/command-reference/index.md b/docs/command-reference/index.md new file mode 100644 index 0000000..83b9685 --- /dev/null +++ b/docs/command-reference/index.md @@ -0,0 +1,45 @@ +# Command Reference + +Complete reference for command-line tools and operations in the Zenith ecosystem. + +## Available Commands + +- [zenithd](zenithd.md) - Main blockchain node commands +- [urbit](urbit.md) - Urbit-related operations + +## Quick Reference + +### Common zenithd Commands +```bash +# Start node +zenithd start + +# Query participants +zenithd query onboarding participants + +# Process attestations +zenithd process-participants +``` + +### Development Commands +```bash +# Build and install +make install + +# Initialize testnet +./scripts/init.sh + +# Generate protobuf +make proto-gen +``` + +### Deployment Commands +```bash +# Deploy with Ansible +ansible-playbook stage0-site.yml -e "mode=start" + +# Using laconic-so +laconic-so deployment --dir deployment start +``` + +For detailed command documentation, see the individual reference pages. \ No newline at end of file diff --git a/docs/command-reference/urbit.md b/docs/command-reference/urbit.md new file mode 100644 index 0000000..0407554 --- /dev/null +++ b/docs/command-reference/urbit.md @@ -0,0 +1,401 @@ +# Urbit Commands + +Command reference for Urbit operations relevant to Zenith network participation, including ship management, desk installation, and network configuration. + +!!! info "Official Urbit Documentation" + For comprehensive Urbit command reference, see the [official Urbit documentation](https://urbit.org/using/os/dojo). This page focuses on Zenith-specific usage patterns. + +## Installation and Setup + +### Urbit Binary Installation +```bash +# Linux installation +curl -L https://urbit.org/install-linux | bash + +# macOS installation +curl -L https://urbit.org/install-macos | bash + +# Verify installation +./urbit --version +``` + +### Ship Boot and Management +```bash +# Boot new ship with keyfile +./urbit -w -k + +# Boot existing ship +./urbit + +# Boot with specific port +./urbit -p 8080 + +# Boot in daemon mode (background) +./urbit -d +``` + +## Zenith-Specific Configuration + +### Zenith Desk Installation +```bash +# Inside Urbit dojo (ship command line) +# Install zenith desk (commands may vary based on current implementation) +|install ~zod %zenith + +# Mount desk for development +|mount %zenith + +# Sync desk updates +|sync %zenith +``` + +### Network Configuration +```bash +# Configure connection to Zenith network +# (Specific configuration commands to be documented) + +# Set network endpoints +# (Configuration details to be documented) +``` + +## Ship Management Commands + +### Inside Urbit Dojo +The Urbit dojo is the command-line interface within your ship. Access it by running your ship and using the prompt. + +#### Basic Ship Operations +```urbit +# Check ship status ++trouble + +# Check network connectivity +.^(@ud %j /=local=/bound) + +# List installed desks ++trouble %desk + +# Check pier information ++trouble %pier +``` + +#### Desk Management +```urbit +# List available desks +|show %desks + +# Install desk from remote ship +|install ~ % + +# Update desk +|sync % + +# Mount desk to Unix filesystem +|mount % + +# Commit changes from Unix filesystem +|commit % +``` + +#### Network Operations +```urbit +# Check network connections +.^(path %j /=local=/bound) + +# Reset network connection +|reset + +# Clear ship cache +|reset %networking +``` + +### Ship Maintenance +```urbit +# Check ship health ++trouble + +# Pack ship (optimize storage) +|pack + +# Backup ship state +# (Performed at Unix level, not in dojo) + +# Update ship runtime +|ota ~zod %kids +``` + +## Zenith Integration Commands + +!!! warning "Development Status" + Zenith-specific Urbit commands are under development. Check the [Zenith desk repository](https://github.com/Zenith-Foundation/zenith-desk) for current command reference. + +### Transaction Submission +```urbit +# Submit transaction to star (conceptual) +:zenith|submit-tx + +# Check transaction status +:zenith|tx-status +``` + +### Network Participation +```urbit +# Check Zenith network status +:zenith|network-status + +# Configure star connection +:zenith|set-star ~ + +# View participation status +:zenith|my-status +``` + +### Application Interaction +```urbit +# List Zenith applications +:zenith|list-apps + +# Launch Zenith application +:zenith|launch + +# Check application status +:zenith|app-status +``` + +## Development Commands + +### Desk Development +```urbit +# Create new desk +|new-desk %my-desk + +# Copy existing desk +|new-desk %my-desk our %base + +# Publish desk changes +|public %my-desk + +# Set desk permissions +|perms %my-desk [%read %self] +``` + +### Testing and Debugging +```urbit +# Test desk functionality +:test %my-desk + +# Debug desk issues ++trouble %desk %my-desk + +# View desk files ++ls %/my-desk +``` + +## Administrative Operations + +### Ship Security +```urbit +# Change ship password +|pass + +# Generate new authentication code +|code + +# List active sessions ++sessions + +# Revoke session ++revoke +``` + +### System Configuration +```urbit +# Set ship timezone +|timezone 'US/Pacific' + +# Configure HTTP settings +|http-server %start + +# Set CORS permissions +|cors-approve '' +``` + +### Backup and Recovery +```bash +# Backup ship at Unix level (ship must be stopped) +tar -czf ship-backup-$(date +%Y%m%d).tar.gz + +# Restore ship from backup +tar -xzf ship-backup-.tar.gz + +# Boot restored ship +./urbit +``` + +## Network Integration + +### Star-Planet Communication +```urbit +# Check sponsorship status +.^(unit ship %j /=sponsor=/our) + +# Request sponsorship from star +# (Typically handled through Urbit Bridge) + +# Configure network routing +# (Usually automatic, but can be debugged) +``` + +### Galaxy-Star Communication +```urbit +# Check galaxy connection +.^(unit ship %j /=galaxy=/our) + +# Verify routing to galaxy ++ping ~ + +# Check network routes +.^(set ship %j /=peers=) +``` + +## Monitoring and Diagnostics + +### Performance Monitoring +```urbit +# Check ship memory usage ++heap + +# Monitor network activity ++verb %j + +# Check event log ++vats + +# Performance statistics ++mass +``` + +### Network Diagnostics +```urbit +# Test connectivity to specific ship ++ping ~ + +# Check NAT configuration +.^(@p %j /=local=/nat) + +# Network trace information ++verb %ames +``` + +### Log Analysis +```bash +# View ship logs (Unix level) +tail -f /.urb/log + +# Filter for specific events +grep "zenith" /.urb/log + +# Analyze network events +grep "ames" /.urb/log +``` + +## Troubleshooting + +### Common Issues + +#### Ship Boot Problems +```urbit +# Reset ship networking +|reset %networking + +# Clear caches +|meld + +# Rebuild from checkpoint +|pack +``` + +#### Network Connectivity +```urbit +# Test basic connectivity ++ping ~zod + +# Reset network stack +|reset + +# Check firewall and port configuration +# (Performed at Unix level) +``` + +#### Desk Installation Issues +```urbit +# Clear desk cache +|reset %clay + +# Reinstall desk +|nuke % +|install ~ % +``` + +### Performance Issues +```urbit +# Optimize ship storage +|pack + +# Clear unnecessary data +|meld + +# Monitor resource usage ++mass +``` + +## Integration Examples + +### Zenith Network Participation +```bash +# 1. Boot ship with proper configuration +./urbit -p 8080 my-ship + +# 2. Install zenith desk (in dojo) +|install ~zod %zenith + +# 3. Configure network connection +:zenith|configure + +# 4. Submit attestation (conceptual) +:zenith|attest +``` + +### Development Workflow +```bash +# 1. Mount desk for development +|mount %zenith + +# 2. Edit files in Unix +nano /zenith/ + +# 3. Commit changes +|commit %zenith + +# 4. Test functionality +:test %zenith +``` + +## Resources + +### Official Documentation +- **Urbit Documentation**: [urbit.org/using](https://urbit.org/using) +- **Dojo Reference**: [urbit.org/using/os/dojo](https://urbit.org/using/os/dojo) +- **Developer Guide**: [urbit.org/guides/core/hoon-school](https://urbit.org/guides/core/hoon-school) + +### Zenith-Specific Resources +- **Zenith Desk**: [GitHub Repository](https://github.com/Zenith-Foundation/zenith-desk) +- **Integration Guide**: [App Development](../documentation/app-development.md) +- **Network Participation**: [Roles & Responsibilities](../overview/roles-responsibilities.md) + +### Community Support +- **Urbit Community**: Official support channels and forums +- **Zenith Developers**: Zenith-specific development support +- **Stack Overflow**: Programming questions and solutions + +!!! note "Evolving Commands" + Zenith-specific Urbit commands are actively being developed. Check the latest desk releases and documentation for updated command reference and usage patterns. \ No newline at end of file diff --git a/docs/command-reference/zenithd.md b/docs/command-reference/zenithd.md new file mode 100644 index 0000000..ff11636 --- /dev/null +++ b/docs/command-reference/zenithd.md @@ -0,0 +1,407 @@ +# zenithd Commands + +Complete command reference for the zenithd blockchain node, including installation, configuration, querying, and network management. + + +## Installation and Setup + +### Building from Source +```bash +# Clone repository +git clone git@github.com:Zenith-Foundation/zenithd.git +cd zenithd + +# Install the zenithd binary +make install + +# Verify installation +zenithd version +``` + +### Development Build +```bash +# Build without installing +make build + +# Build for Linux +make build-linux + +# Check dependencies +make go.sum +``` + +## Node Initialization and Management + +### Initialize Node +```bash +# Initialize and start a local testnet +./scripts/init.sh + +# Start fresh (removes all data) +./scripts/init.sh clean + +# Initialize without starting (for configuration) +./scripts/init.sh --bare +``` + +### Start Node +```bash +# Start with default configuration +zenithd start + +# Start with Azimuth watcher endpoint +zenithd start --azimuth-watcher-endpoint + +# Start in galaxy mode with Janus server +zenithd start --janus-node-mode galaxy --janus-config /path/to/janus-config.yaml + +# Start in star mode with Janus server +zenithd start --janus-node-mode star --janus-config /path/to/janus-config.yaml + +# Configure server address +zenithd start --zenith-server-address localhost:9473 +``` + +### Node Status +```bash +# Check node status +zenithd status + +# Check sync status (with jq formatting) +zenithd status | jq .sync_info + +# Get node ID and address +zenithd cometbft show-node-id +``` + +## Participant Management + +### Process Participants +Verify participant attestations during stage transitions: + +```bash +# Verify all participants' ownership claims +zenithd process-participants + +# Example +zenithd process-participants ./chain-state.json ./verified-participants.json +``` + +This command: +- Checks cryptographic signatures from both Ethereum and Cosmos accounts +- Verifies Azimuth point ownership through the Azimuth watcher +- Outputs only verified participants for network initialization + +### Genesis Management +```bash +# Export chain state +zenithd export | jq > chain-state.json + +# Add verified participants to genesis +zenithd genesis add-zenith-genesis-accounts [,...] + +# Example +zenithd genesis add-zenith-genesis-accounts ./verified-participants.json '100000$Z' + +# Populate sponsorship index from verified participants +zenithd genesis populate-sponsorship \ + --participants-file ./verified-participants.json \ + --eth-block-hash \ + --azimuth-watcher-endpoint + +# Create treasury allocations from config +zenithd genesis create-treasury --config /path/to/treasury-config.toml +``` + +## Query Commands + +### Onboarding Module +```bash +# List all participants +zenithd query onboarding participants + +# Get specific participant by zenith address +zenithd query onboarding get-participant-by-address
+ +# Get participants by point +zenithd query onboarding get-participants-by-point + +# Get module parameters +zenithd query onboarding params +``` + +### Scry Oracle Module +```bash +# Get complete binding information for a path +zenithd query scryoracle get-binding-by-path + +# Get path to hash mappings for a path prefix +zenithd query scryoracle get-bindings-by-path-prefix + +# Get path to hash mappings added at a block number +zenithd query scryoracle get-bindings-by-block-number + +# Get path to hash mappings added in a block range +zenithd query scryoracle get-bindings-in-block-range +``` + +### Zenith Module +```bash +# Get Zenith address for a given point / Urbit id +zenithd query zenith get-address-by-point + +# Get balances for Zenith address of a given point / Urbit id +zenithd query zenith get-balances-by-point + +# Get sponsorship details for a given point / Urbit id +zenithd query zenith get-sponsorship-by-point + +# Get the latest ETH block height as seen by Zenith +zenithd query zenith get-eth-height + +# Get module parameters +zenithd query zenith params +``` + +### Treasury Module +```bash +# Get treasury distribution (optionally filtered by category) +zenithd query immutabletreasury distribution + +# Get allocations for a specific address (optionally filtered by point) +zenithd query immutabletreasury allocations-by-address
[point] + +# Get accrual state for a specific address and point +zenithd query immutabletreasury accrual-state
+ +# Get all accrual states for an address +zenithd query immutabletreasury accrual-states
+ +# Get claim state for a specific address +zenithd query immutabletreasury claim-state
+ +# Get claimable amount for a specific address +zenithd query immutabletreasury claimable-amount
+ +# Get balance yet to be accrued for a specific address +zenithd query immutabletreasury balance-yet-to-be-accrued
+ +# Get balance yet to be unlocked for a specific address +zenithd query immutabletreasury balance-yet-to-be-unlocked
+ +# Get current block rewards state +zenithd query immutabletreasury block-rewards-state + +# Get module parameters +zenithd query immutabletreasury params +``` + +### Standard Cosmos SDK Queries +```bash +# Account information +zenithd query account
+ +# Token balances +zenithd query bank balances
+ +# Validator information +zenithd query staking validators + +# Delegation information +zenithd query staking delegations + +# Governance proposals +zenithd query gov proposals +``` + +## Transaction Commands + +### Standard Transactions +```bash +# Send tokens +zenithd tx bank send --fees + +# Delegate tokens +zenithd tx staking delegate --from + +# Submit governance proposal +zenithd tx gov submit-proposal --from + +# Vote on proposal +zenithd tx gov vote yes --from +``` + +## Key Management + +### Create and Manage Keys +```bash +# Add new key +zenithd keys add + +# List keys +zenithd keys list + +# Show key address +zenithd keys show --address + +# Export key +zenithd keys export + +# Import key +zenithd keys import +``` + +## Configuration + +### Environment Variables +```bash +# External data sources +export AZIMUTH_WATCHER_ENDPOINT= + +# Chain configuration +export CHAIN_ID="zenith-testnet-stage0" +export ONBOARDING_ENABLED=true +export ENABLE_STALLED_ETH_HEIGHT_SLASHING=true + +# Janus configuration +export JANUS_NODE_MODE=galaxy # or "star" or "" +export JANUS_CONFIG=/path/to/janus-config.yaml +``` + +### Configuration Files +```bash +# Initialize configuration +zenithd init --chain-id + +# Edit configuration +nano ~/.zenithd/config/config.toml +nano ~/.zenithd/config/app.toml +``` + +## Development Commands + +### Protobuf Development +```bash +# Generate all protobuf code +make proto-gen + +# Full protobuf workflow (format, lint, generate) +make proto-all + +# Format protobuf files +make proto-format + +# Lint protobuf files +make proto-lint + +# Generate Swagger documentation +make proto-swagger-gen +``` + +### Testing +```bash +# Run all tests +go test ./... + +# Run tests with verbose output +go test -v ./... + +# Run specific test package +go test ./x/onboarding + +# Run with race detector +go test -race ./... +``` + +## Network Operations + +### Validator Operations +```bash +# Create validator +zenithd tx staking create-validator \ + --amount= \ + --pubkey=$(zenithd cometbft show-validator) \ + --moniker="" \ + --chain-id= \ + --from= + +# Edit validator +zenithd tx staking edit-validator \ + --moniker="" \ + --website="" \ + --from= +``` + +### Node Connection +```bash +# Add persistent peers +zenithd config set config.p2p.persistent_peers "," + +# Connect to specific node +zenithd config set config.p2p.seeds "" +``` + +## Troubleshooting + +### Common Issues +```bash +# Reset node data (dangerous!) +zenithd unsafe-reset-all + +# Check node logs +journalctl -u zenithd -f + +# Validate genesis file +zenithd validate-genesis + +# Check configuration +zenithd config validate +``` + +### Debug Information +```bash +# Get detailed status +zenithd status --output json | jq + +# Check consensus state +zenithd query consensus-state + +# Monitor mempool +zenithd query mempool +``` + +## Examples + +### Complete Node Setup +```bash +# 1. Install +make install + +# 2. Initialize +zenithd init mynode --chain-id zenith-testnet + +# 3. Configure +export AZIMUTH_WATCHER_ENDPOINT="https://azimuth.dev.vdb.to/graphql" + +# 4. Start +zenithd start +``` + +### Query Participant Information +```bash +# Check if address is onboarded +zenithd query onboarding get-participant-by-address zenith1abc... + +# Get their address by point +zenithd query zenith get-address-by-point 123 + +# Get their balances by point +zenithd query zenith get-balances-by-point 123 + +# Check their token balance by address +zenithd query bank balances zenith1abc... +``` + +## HTTP RPC/API Queries + +For HTTP/REST API queries and the Janus Server API, see the [zenithd API Reference](../api/zenithd.md). \ No newline at end of file diff --git a/docs/documentation/app-development.md b/docs/documentation/app-development.md new file mode 100644 index 0000000..2b1b324 --- /dev/null +++ b/docs/documentation/app-development.md @@ -0,0 +1,15 @@ +# App Development + +Develop applications on the Zenith network that leverage Urbit identity and blockchain consensus for decentralized application experiences. + +## Overview + +Application development on Zenith combines the unique identity system of Urbit with the programmability of blockchain technology, enabling developers to create applications that respect user sovereignty while providing decentralized consensus. + +## Getting Started + +### Zenith Desk +The primary development entry point is through the Zenith desk, an Urbit application suite available at [https://github.com/Zenith-Foundation/zenith-desk](https://github.com/Zenith-Foundation/zenith-desk) that provides the necessary tools and libraries for Zenith integration. Install the #zenith-desk on your Urbit ship to access the application development framework and tools. See the [Zenith Desk API documentation](../api/zenith-desk-api.md) for detailed API reference. + +### Zenith Karma +Zenith Karma is an example application demonstrating Zenith integration patterns, available at [https://github.com/Zenith-Foundation/zenith-karma](https://github.com/Zenith-Foundation/zenith-karma). It provides reference implementations for common development scenarios and serves as a practical guide for building Zenith-enabled applications. \ No newline at end of file diff --git a/docs/documentation/azimuth.md b/docs/documentation/azimuth.md new file mode 100644 index 0000000..08942a7 --- /dev/null +++ b/docs/documentation/azimuth.md @@ -0,0 +1,41 @@ +# Azimuth + +Azimuth is Urbit's identity registry deployed on the Ethereum blockchain. It serves as the source of truth for Urbit point ownership and network identity. + +## What is Azimuth? + +Azimuth is an ERC-721 based public key infrastructure (PKI) that manages Urbit identities. Each Urbit identity is represented as an NFT on Ethereum, providing cryptographic proof of ownership and enabling decentralized identity management. + +**Key Features:** + +- Galaxies, stars, planets, moons, and comets form a tiered hierarchical identity system +- Cryptographic proof of identity ownership stored on Ethereum +- Higher-tier points sponsor lower-tier points, establishing network relationships +- All identity operations are recorded on Ethereum for transparency + +## Azimuth in Zenith + +Zenith uses Azimuth as the basis for network participation and governance: + +**Validator Eligibility**: Only verified Azimuth galaxy owners can become validators on Zenith. + +**Transaction Bundling**: Star owners participate as transaction bundlers, aggregating transactions from planets. + +**Identity Verification**: The lockdrop process requires cryptographic attestations linking Azimuth ownership to Zenith accounts. + +**Ownership Tracking**: The Azimuth Watcher monitors ownership changes in real-time, automatically jailing and slashing validators who transfer their galaxy ownership. + +**Sponsorship Model**: Zenith preserves Urbit's sponsorship relationships, with stars submitting bundles to their sponsoring galaxy validators. + +## Learn More + +- **Official Azimuth Documentation**: [docs.urbit.org/urbit-id/what-is-urbit-id](https://docs.urbit.org/urbit-id/what-is-urbit-id) +- **Azimuth Contracts**: [github.com/urbit/azimuth](https://github.com/urbit/azimuth) +- **Bridge Interface**: [bridge.urbit.org](https://bridge.urbit.org) - Manage your Azimuth points +- **Network Explorer**: [network.urbit.org](https://network.urbit.org) - View the Azimuth registry + +## Related Documentation + +- [Watchers](watchers.md) - Learn about the Azimuth Watcher that monitors the registry +- [Roles & Responsibilities](../overview/roles-responsibilities.md) - Understand how Azimuth points map to network roles +- [Lockdrop Onboarding](../overview/lockdrop-onboarding.md) - See how Azimuth ownership is verified during onboarding diff --git a/docs/documentation/deployments.md b/docs/documentation/deployments.md new file mode 100644 index 0000000..9fd8d5f --- /dev/null +++ b/docs/documentation/deployments.md @@ -0,0 +1,47 @@ +# Deployments + +## Overview + +Zenith network deployments progress through multiple stages, each with different infrastructure requirements and operational models. + +## Stage 0: Onboarding Phase + +Stage 0 is operated entirely by Tlon with no external infrastructure required. This onboarding phase runs on a single centralized validator operated by Tlon for participant onboarding and attestation collection. External participants only need to interact with the onboarding application to submit their attestations and lockdrop commitments. + +## Token Generation Event (TGE) + +When Stage 0 is manually halted, anyone can recreate the genesis state from Stage 0 data following the TGE process. The TGE process verifies all attestations, validates point ownership against the Azimuth registry, and generates the complete genesis file with initial validator set and token allocations. + +## Stage 1: Initial Mainnet + +Stage 1 marks the transition to mainnet where validators begin joining the network. Galaxy operators deploy validator nodes while star operators deploy bundling nodes. + +### Validator Node Deployment + +Galaxy operators joining as validators configure their deployment using the zenith-ansible tooling. Key configuration requirements include setting the validator data directory, choosing a human-readable moniker for network identification, and configuring the Ethereum RPC endpoint for Azimuth monitoring. Operators must specify their Urbit galaxy ID and associated star ID along with peer connections to the bootstrap node. + +The deployment process involves exporting the private key for the galaxy owner's account, which is required for both validator operations and the associated star's Janus service. Operators setup their validator node with appropriate port configurations to avoid conflicts, pull the necessary docker images, and initialize deployment directories. After starting the validator node, they create their validator registration using the exported private key. + +Verification includes checking the node's sync status with the network, reviewing logs for proper operation, and confirming the validator appears in the bonded validator set. The node must maintain connectivity to the network and successfully participate in consensus to earn token accrual. + +### Star Node Deployment + +Star operators deploy follower nodes running in star mode to participate in the Janus transaction bundling system. These nodes bundle transactions from planets and submit them to their sponsoring galaxy without becoming validators themselves. + +Configuration involves setting the star node data directory, moniker, and network connectivity including peers pointing to the sponsoring galaxy's validator node. Operators specify their Urbit star ID and configure the Janus galaxy URL pointing to their sponsor galaxy's Janus API endpoint. The star node requires the private key for the account that onboarded the star point. + +The deployment process includes modifying port configurations to avoid conflicts with other nodes, pulling docker images, and setting up deployment directories. After starting the star node, operators verify it syncs with the Stage 1 chain by checking sync status and reviewing logs. + +Once synced, the star node exposes a Janus API endpoint to accept transactions from planets. Transactions are bundled together, signed by the star, and forwarded to the sponsoring galaxy's Janus endpoint for inclusion in blocks. The star earns rewards from transaction bundling fees and optional network services. + +### Infrastructure Requirements + +Validator nodes require high-performance multi-core processors with substantial RAM for validator operations and reliable SSD storage. High-bandwidth, low-latency internet connections are essential along with backup systems for failover capabilities. Star nodes need multi-core processors capable of transaction aggregation with moderate RAM and storage requirements. Both node types require stable connectivity, health monitoring systems, and secure key management practices. + +### Monitoring and Observability + +Operators should monitor node sync status, log output for errors, and resource utilization including CPU, RAM, and storage. Network connectivity and peer connections require regular monitoring along with block production participation and transaction processing rates. Alerting systems should notify operators of issues requiring intervention. + +### Security Hardening + +Secure key management is critical for both validator and star operations. Operators should implement proper firewall configurations, restrict administrative access to authorized personnel, and maintain comprehensive audit logging. Data should be encrypted at rest and in transit with regular backups stored securely. Disaster recovery procedures should be tested periodically to ensure rapid recovery from failures. diff --git a/docs/documentation/epbs.md b/docs/documentation/epbs.md new file mode 100644 index 0000000..1042c4e --- /dev/null +++ b/docs/documentation/epbs.md @@ -0,0 +1,33 @@ +# ePBS (Enshrined Proposer Builder Separation) + +## Overview + +Enshrined Proposer Builder Separation (ePBS) is a protocol-level mechanism that separates the roles of block proposers and block builders to improve censorship resistance and MEV (Maximal Extractable Value) distribution in blockchain networks. + +## Zenith's ePBS Implementation + +Zenith implements ePBS through a lane-based architecture that prioritizes transaction bundles from associated and sponsored stars. Validator node operators configure their Galaxy point ID along with an associated Star ID in the [Janus configuration](https://github.com/Zenith-Foundation/zenithd/blob/main/janus/config.template.yaml#L23-L45). The associated star submits its bundles to the Galaxy Janus directly in-process without going through external endpoints, whereas standalone stars submit bundles to the Galaxy Janus over HTTP. + +### Lane-Based Architecture + +The Block SDK provides a lane abstraction over block construction and mempool management. Lanes split the block construction across multiple dedicated channels, with each lane maintaining its own mempool. The system processes `PrepareProposal` and `ProcessProposal` handlers through these lanes to ensure fair block space allocation. + +The current [lane configuration](https://github.com/Zenith-Foundation/zenithd/blob/main/app/lanes/setup.go#L57) prioritizes block space in the following order. The [associated star lane](https://github.com/Zenith-Foundation/zenithd/blob/main/app/lanes/associated_star.go) receives 15% of block space and occupies the top of the block. The [sponsored stars lane](https://github.com/Zenith-Foundation/zenithd/blob/main/app/lanes/sponsored_stars.go) receives 75% of block space for bundles from other sponsored stars. The default lane handles regular transactions and takes up remaining block space, though this lane will be removed in future implementations. + +### Bundle Processing + +The Galaxy Janus maintains a FIFO bundle queue that feeds into the laned mempool system. A mempool syncer reads bundles from this queue every 100ms and [inserts them](https://github.com/Zenith-Foundation/zenithd/blob/main/app/lanes/utils/mempool_syncer.go#L61-L78) into the appropriate lane based on the bundle's origin. The laned mempool processes lanes in priority order, with the associated star lane accepting only bundles from the configured associated star, and the sponsored star lane accepting bundles from other sponsored stars tracked in the state. + +In the current MVP implementation, the laned mempool allows direct transaction submission with these transactions ending up in the default lane. Cross-galaxy bundles are not yet supported in this version. + +### Block Proposal + +When a Galaxy's turn arrives to propose a block, each lane includes bundles from their respective mempools until exhausting their quota. The associated star lane fills the first 15% of block space with bundles from the associated star. The sponsored stars lane then fills the next 75% of block space with bundles from sponsored stars. Any bundles that don't fit remain in the mempools for consideration in the next block. The default lane uses any remaining block space for non-bundle transactions. + +During block proposal in `PrepareProposal`, bundles are splayed out with all transactions from each bundle included in the block while maintaining their original order. To enable validation by non-leader validators, the system adds a pseudo transaction called [`IncludeBundleTx`](https://github.com/Zenith-Foundation/zenithd/blob/main/app/lanes/utils/include_bundle_tx.go) as a prefix to each bundle. + +### Validation Process + +In `ProcessProposal`, non-leader validators validate the bundles included in the block proposal by verifying the bundle signatures contained in each `IncludeBundleTx`. The `IncludeBundleTx` contains the Star ID and bundle signature, allowing validators to distinguish between bundles in the transaction list. This pseudo transaction is ignored during normal block execution. + +The `ProcessProposal` validation also checks block structure and rejects malformed proposals, such as bundles appearing in the default lane. In the `PreBlocker` hook, the system emits a `bundle_inclusion` [event](https://github.com/Zenith-Foundation/zenithd/blob/main/abci/proposal.go#L249-L259) for each `IncludeBundleTx` to track bundle inclusion in blocks. \ No newline at end of file diff --git a/docs/documentation/index.md b/docs/documentation/index.md new file mode 100644 index 0000000..46c3a03 --- /dev/null +++ b/docs/documentation/index.md @@ -0,0 +1,14 @@ +# Documentation + +Technical documentation for developers, operators, and advanced users of the Zenith ecosystem. + +- [Network Stages](network-stages.md) - Two-stage deployment model from lockdrop to mainnet +- [Azimuth](azimuth.md) - Urbit's identity registry on Ethereum +- [Operator Deployments](deployments.md) - Node deployment and configuration +- [Ship Hosting](urbit-ship-hosting.md) - Running your ship on the Urbit Network +- [Janus Server](janus.md) - Transaction aggregation layer architecture +- [Scry Oracle](scry-oracle.md) - Decentralized oracle system for off-chain data +- [ePBS](epbs.md) - Enshrined Proposer-Builder Separation +- [App Development](app-development.md) - Building applications on Zenith +- [Light Contracts](light-contracts.md) - Lightweight on-chain programmability +- [Watchers](watchers.md) - Blockchain indexing and monitoring services \ No newline at end of file diff --git a/docs/documentation/janus.md b/docs/documentation/janus.md new file mode 100644 index 0000000..067084a --- /dev/null +++ b/docs/documentation/janus.md @@ -0,0 +1,65 @@ +# Janus + +Janus is a critical component in the Zenith ecosystem that serves as a transaction aggregation layer bridging Urbit ships and the Zenith blockchain. Named after the two-faced Roman god, Janus faces both directions: toward Urbit ships and toward the Zenith consensus layer. + +!!! info "Integrated into zenithd" + Janus functionality is integrated into zenithd. Galaxy validators run zenithd in validator mode with a built-in Janus server for their associated star. Independent star operators run zenithd in star mode which includes the Janus bundling service. + +## Overview + +Janus handles the aggregation of transactions and scry bindings between different tiers of Urbit ships and the Zenith blockchain, enabling efficient batch processing and reduced on-chain overhead. + +## Architecture + +The Janus system follows a simplified hierarchical model: + +``` +Planet → Star Janus → Galaxy +[submit txs] [bundle txs] [build blocks from bundles] +``` + +### Key Design Principles +The system uses a simplified hierarchy where stars bundle transactions and send them to galaxy validators who build blocks. Galaxy validators run zenithd in validator mode with a built-in Janus server for their associated star that runs in-process. Independent stars run zenithd in star mode and submit bundles to galaxy validators over HTTP. This enables efficient aggregation where transactions are bundled and scry bindings are batched before blockchain submission. + +## Star Node Responsibilities + +Independent stars run zenithd in star mode (which includes the Janus bundling service) to gather transactions from sponsored planets and aggregate multiple transactions into efficient bundles. They collect and batch scry bindings from the Urbit network and submit bundles and batches to galaxy validators. Associated stars (owned by galaxy validators) have their Janus server run in-process within zenithd validator mode. + +## Technical Components + +### Transaction Bundling +Transaction bundling collects individual transactions from planets and creates efficient bundles to reduce blockchain overhead. Bundles are signed with the star's cryptographic key and submitted to galaxy validators. These bundles are prioritized and processed through Zenith's [ePBS (Enshrined Proposer-Builder Separation)](epbs.md) system, which uses lane-based architecture to ensure fair block space allocation. + +### Scry Binding Aggregation +Scry binding aggregation collects path-to-hash mappings from the Urbit network and batches multiple bindings for efficient submission. It provides individual signature verification for each binding, enabling off-chain data to be aggregated on-chain through consensus. + +### Cryptographic Security +The system uses secp256k1 cryptography for signing and integrates with Azimuth PKI for signature verification, providing proof of data integrity and origin. + +## Configuration + +Janus uses YAML configuration files with key sections: + +### Node Identity +Configuration includes node type (currently only "star" nodes supported), node ID (Urbit @p name or numeric identifier), and port configuration. + +### Network Settings +Network settings specify the chain ID for the target Zenith network, zenithd URLs for failover support, and the Azimuth watcher GraphQL endpoint. + +### Operational Parameters +Operational parameters define the maximum transactions per bundle, bundle timeout settings, scry batch size and timeout, and retry configuration for network failures. + +## API Endpoints + +Independent stars running zenithd in star mode expose HTTP endpoints including POST /submit/tx to accept transactions from planets in Cosmos SDK protobuf format, POST /submit/scry to accept scry bindings with individual signatures, GET /health for monitoring health checks, and GET /status for node status and operational metrics. + +## Integration with zenithd + +### Built-in Janus Server +Galaxy validators running zenithd in validator mode include a built-in Janus server for their associated star that runs in-process. Galaxy validators accept bundles and batches from independent stars, validate incoming data through consensus mechanisms, integrate with the scry oracle module, and process data through ABCI vote extensions. + +### Data Flow +1. Planets submit transactions to their sponsoring star's Janus +2. Stars (both associated and independent) bundle transactions and batch scry bindings +3. Independent stars submit bundles to galaxy validators over HTTP; associated stars' bundles are handled in-process +4. Galaxy validators process data through consensus and store in modules diff --git a/docs/documentation/light-contracts.md b/docs/documentation/light-contracts.md new file mode 100644 index 0000000..79dc8b7 --- /dev/null +++ b/docs/documentation/light-contracts.md @@ -0,0 +1,8 @@ +# Light Contracts + +!!! warning "Future Development" + Light Contracts are a planned feature for future Zenith development. This page contains conceptual information and design considerations for the proposed system. + +Light Contracts represent a lightweight approach to programmable functionality on the Zenith blockchain, designed to enable flexible application development while maintaining focus on Urbit identity and consensus. Unlike traditional smart contracts, Light Contracts use a simpler execution model optimized for Zenith's specific use cases, with native understanding of Azimuth point ownership and sponsorship relationships. They enable user-deployable logic for identity-based applications, economic applications, and infrastructure services without requiring network upgrades. + +Key features include access control based on Azimuth point ownership, integration with the Scry Oracle for off-chain Urbit data, $Z token handling, and deterministic execution with gas metering. Light Contracts are user-deployable without core development (unlike Cosmos SDK modules) and offer lower overhead than full VM systems like Ethereum, with execution optimized for blockchain resource constraints and quick execution times compatible with Cosmos SDK consensus. The design and implementation will be driven by community needs and governance decisions. \ No newline at end of file diff --git a/docs/documentation/network-stages.md b/docs/documentation/network-stages.md new file mode 100644 index 0000000..1f00baa --- /dev/null +++ b/docs/documentation/network-stages.md @@ -0,0 +1,127 @@ +# Network Stages + +The Zenith network evolves through a carefully orchestrated multi-stage process, beginning with a testnet phase and culminating in a fully operational standalone blockchain. The design prioritizes phased decentralization, secure onboarding, and alignment with Azimuth-based identities. + +## Timeline Overview + +The launch and evolution spans three main stages plus an intermediate verification phase: + +```mermaid +gantt + title Zenith Network Evolution + dateFormat X + axisFormat %s + section Stage 0 + Lockdrop (6mo) :0, 180 + Incentivized Testnet (6mo) :0, 180 + section Verification + TGE :180, 190 + section Stage 1 + Stage 1 :190, 220 + section Stage 2 + Stage 2 :220, 250 + section Stage 3 + Stage 3 :250, 300 +``` + +--- + +## Stage 0: Onboarding Phase (6 months) + +### Overview +Stage 0 is operated entirely by Tlon with no external infrastructure required. This onboarding phase runs on a single validator for participant onboarding and attestation collection. External participants only need to interact with the onboarding application to submit their attestations and lockdrop commitments. + +**Duration**: 6 months +**Operator**: Single validator operated by Tlon +**Purpose**: Participant onboarding and lockdrop process + +### Separate Testnet +During the same 6-month Stage 0 period, a separate testnet operates concurrently, allowing participants to test network functionality before mainnet launch. + +### Key Activities + +#### Lockdrop Participation +Participants must deposit their Azimuth points in the Ethereum L1 lockdrop contract, demonstrating real commitment to network success. Locking a point is mandatory to receive any $Z in the future and secures rights within the Zenith Network. + +#### Attestation Collection +Participants submit cryptographic proofs of Azimuth point ownership, which are collected but not verified during Stage 0. All attestation and lockdrop data is collected on the centralized chain and processed later during the verification phase. + +#### Participant Types and Requirements + +Stage 0 participation is open to galaxy and star owners. See [Roles & Responsibilities](../overview/roles-responsibilities.md) for detailed ownership requirements and responsibilities for each participant type. + +#### Parallel Testnet for Planets + +During the official Stage 0 onboarding with lockdrop, a parallel testnet operates where planets can sign up to the Tlon App and receive fake $Z tokens for testing purposes. This allows planets to test network functionality and prepare for Stage 1 launch without participating in the lockdrop. + +### Technical Characteristics +Stage 0 uses znt (Zenith Onboarding Token) for transaction fees on the Stage 0 zenithd testnet. Tokens are delivered via faucet in the onboarding application. Stage 0 operates with a single Tlon-operated validator node. The simplified chain focuses on data collection with centralized but temporary security for onboarding. This testnet has no economic value. + +--- + +## Token Genesis Event (TGE) + +### Overview +The TGE marks the transition from testnet to mainnet, creating the genesis.json that initiates the Zenith mainnet. + +### Key Processes + +#### Full Supply Creation +The full supply of $Z is generated and allocated to lockdrop participants, foundation, investors, and team members using data from the onboarding app and supplemental CSV files. Every unit of $Z is accounted for before launch, ensuring complete transparency. + +#### Verification and Validation +All Stage 0 attestations are cryptographically verified, and claimed point ownership is checked against the live Azimuth registry. Only verified participants proceed to Stage 1, where they receive appropriate token allocations. + +#### Genesis File Generation +The complete network state is prepared for Stage 1 launch, including the initial validator set from verified galaxy owners. All allocations are encoded in the genesis state with custom modules configured for production. + +--- + +## Stage 1: Initial Mainnet Launch + +### Overview +Stage 1 begins immediately following TGE with a controlled mainnet launch, initially operated by Tlon with gradual validator onboarding. + +**Duration**: Until community governance vote to transition to Stage 2 +**Initial Validator**: Single Tlon bootstrap node, expanding to multiple galaxies +**Participation**: Restricted to lockdrop participants only + +### Bootstrap Validator +At the start of Stage 1, Tlon runs the bootstrap validator and publishes the peer node ID. Galaxy validators then join as subsequent validators by connecting to this bootstrap node. This controlled launch ensures network stability before full decentralization. + +### Token Economics + +Stage 1 operates with two tokens: $Z serves as native currency for fees and governance (locked in the lockdrop module), and stakez is a non-transferable token used for validator mechanics and chain operations. + +#### Initial Token Access +Market makers receive 100% of their allocation immediately, while the foundation can claim 50% of the market maker allocation. Other participants initially have access to approximately 5% of their allocation, with remaining tokens accruing based on network participation. + +### Participation Mechanics + +#### Validator Requirements (Galaxies) +Galaxy validators must actively sign blocks to earn $Z accrual while maintaining Azimuth galaxy ownership and running validator node infrastructure. Validators are automatically jailed and slashed if they lose point ownership. + +#### Bundler Benefits (Stars) +Star operators must actively bundle transactions and submit them to their sponsoring galaxy through the Janus service to earn rewards from transaction fees. + +### Security Mechanisms +Validators are automatically jailed and slashed if they lose Azimuth point ownership. Jailing removes validators from the active set and stops new token accrual, while slashing causes loss of existing tokens. Economic penalties include loss of $Z accrual for inactive participation. + +### Stage 1 Completion Criteria +Stage 1 ends when the community votes via governance to transition to Stage 2. + +--- + +## Stage 2: Migration from stakez to ZSN + +Stage 2 introduces Zenith Staking NFTs (ZSN) as a replacement for stakez tokens, enabling tradable validation and bundling rights backed by economic value. Each stakez position converts 1:1 to a corresponding ZSN, with galaxies receiving validator rights NFTs and stars receiving bundling rights NFTs. This migration moves the network toward a mature Proof-of-Authority system where network permissions become tradable marketplace assets, adding economic weight to Urbit's sponsorship relationships while maintaining all existing Azimuth rights and properties. + +--- + +## Stage 3: Standalone Zenith + +Stage 3 represents the final evolution to a fully sovereign blockchain, independent of external dependencies including Ethereum and the Azimuth registry. The network becomes entirely community-controlled through ZSN and $Z token holders, with validator selection market-based through tradable ZSN rights. This stage begins with a protocol upgrade hardfork decided by community governance, creating a self-sustaining network with all decisions made by token holders while maintaining operational continuity and preserving all existing rights. + +## Next Steps + +Learn about [Deployments](deployments.md) for validator and star node deployment in Stage 1, or explore the [Tokenomics](../tokenomics/index.md) to understand the economic model across all stages. \ No newline at end of file diff --git a/docs/documentation/scry-oracle.md b/docs/documentation/scry-oracle.md new file mode 100644 index 0000000..4de6f42 --- /dev/null +++ b/docs/documentation/scry-oracle.md @@ -0,0 +1,98 @@ +# Scry Oracle + +The Scry Oracle is a decentralized oracle system that aggregates off-chain data from the Urbit network and makes it available on the Zenith blockchain through consensus-based validation. It bridges off-chain Urbit network data with on-chain blockchain state, enabling applications to access verified Urbit data through standard blockchain queries. + +## What is "Scry" Data? + +In the Urbit ecosystem, "scry" refers to a read-only query mechanism for accessing data stored on Urbit ships. Scry paths represent specific pieces of data in the Urbit network, such as: + +``` +/~zen/metadata-store/associations/groups/random-group/json +/~zen/group-store/groups/random-group/json +/~zen/group-store/members/random-group/json +/~zen/publish/posts/2025.3.6..15.30.20..0000/json +``` + +## Architecture + +### Data Collection +The Scry Oracle operates through a multi-step consensus process: + +1. **External Data Collection**: Janus servers collect scry bindings from the Urbit network +2. **Batch Submission**: Janus servers submit batches of scry bindings to zenithd validators +3. **Vote Extensions**: Validators collect and validate the submitted data using ABCI++ vote extensions +4. **Consensus Aggregation**: Data is aggregated through the consensus mechanism +5. **State Storage**: Validated data is stored in the scryoracle module state + +### Path-to-Hash Mapping + +The oracle stores mappings from scry paths to their corresponding data hashes: +- **Path**: The scry location (e.g., `/~zen/group-store/groups/random-group/json`) +- **Hash**: Cryptographic hash of the data stored at that path +- **Integrity**: Hash provides data integrity verification without revealing content + +## Technical Implementation + +### ABCI++ Integration + +ABCI++ is the Application Blockchain Interface used in Cosmos SDK that enables advanced features for collecting and validating external data. It provides vote extensions that allow validators to attach additional information to their votes during consensus rounds, enabling the Scry Oracle to aggregate off-chain data through a decentralized process. + +The Scry Oracle leverages these ABCI++ features: +- **Vote Extensions**: Validators collect external data during consensus rounds +- **Proposal Handlers**: Aggregate vote extension data through consensus +- **EndBlocker Processing**: Apply validated data to module state + +### Data Flow +1. **Janus Submission**: Scry binding batches submitted to zenithd HTTP endpoints +2. **Validation**: Incoming data validated for structure and signatures +3. **Vote Extension Collection**: Validators include data in vote extensions +4. **Consensus Processing**: Proposal handler aggregates data through consensus +5. **State Updates**: Valid data stored in module keepers for queries + +### Deduplication and Filtering +- **Duplicate Removal**: Identical scry bindings are filtered out +- **Validation**: Only properly formatted and signed data is processed +- **Consensus Agreement**: Data must be agreed upon by validator majority + +## Query Interface + +The Scry Oracle provides several query methods for accessing stored data. + +### Available Queries + +- **GetHashByPath**: Retrieve hash values for specific scry paths +- **GetBindingsByPathPrefix**: Filter bindings by path prefix +- **GetBindingsByBlockNumber**: Query bindings at specific blocks +- **GetBindingsInBlockRange**: Retrieve bindings within block ranges + +All queries support historical data access, allowing applications to query oracle data from specific points in blockchain history. + +### API Access + +Applications can access oracle data through: + +- **gRPC**: Direct module queries +- **REST API**: HTTP endpoints for web applications +- **CLI**: Command-line tools for manual queries + +## Data Sources + +### Janus Integration + +Janus servers serve as the primary source for collecting scry data from the Urbit network. They submit multiple scry bindings together for efficient batch processing, with individual signatures verified for each binding. Data is collected from across the Urbit network hierarchy. + +### External HTTP Endpoints + +Optional HTTP endpoints provide a fallback mechanism for additional data sources, useful for development and testing scenarios. Multiple data sources improve system reliability through redundancy. + +## Use Cases + +The Scry Oracle enables applications to: + +- Verify off-chain Urbit data integrity +- Query Urbit data from blockchain applications through cross-network queries +- Perform historical analysis of Urbit network state changes +- Obtain cryptographic proofs of Urbit data +- Monitor Urbit network activity and troubleshoot cross-network data flow issues + +The Scry Oracle bridges the Urbit ecosystem and blockchain applications, providing verified access to off-chain Urbit data through decentralized consensus mechanisms. \ No newline at end of file diff --git a/docs/documentation/urbit-ship-hosting.md b/docs/documentation/urbit-ship-hosting.md new file mode 100644 index 0000000..fecc76a --- /dev/null +++ b/docs/documentation/urbit-ship-hosting.md @@ -0,0 +1,62 @@ +# Urbit Ship Hosting + +Requirements and best practices for hosting Urbit ships as part of Zenith network participation. + +## Overview + +Participation in the Zenith network requires hosting self-hosted Urbit ships for different roles. This page covers the infrastructure requirements, hosting options, and operational considerations for running Urbit ships as part of Zenith ecosystem participation. + +## Role-Based Requirements + +### Galaxy Operators +Galaxy operators must host the galaxy ship corresponding to their attested galaxy point and a star ship owned by the same Zenith account and sponsored by their galaxy. Both ships must be accessible and operational for network participation. + +### Star Operators +Star operators must host the Urbit ship for their attested star point while maintaining connectivity to sponsored planets and the sponsoring galaxy. High availability is essential for transaction aggregation services. + +### Planet Users +Planet users host their planet ship with the #zenith-desk installed, maintaining connection to their sponsoring star and ensuring their ship can access Zenith-enabled applications. + +## Operational Procedures + +### General Hosting Guidelines + +Star and Galaxy hosting can be done by following the official Urbit documentation at [docs.urbit.org/user-manual/running](https://docs.urbit.org/user-manual/running), with a few caveats for Galaxies (e.g., the port must be their point number plus some constant). + +### Ship Setup and Zenith Configuration +```bash +# Download and install Urbit +curl -L https://urbit.org/install-linux | bash + +# Boot ship with pier directory +./urbit -w -k +``` + +Once your ship is running, install the zenith-desk from the dojo: +``` +|install ~sampel-palnet %zenith-desk +``` + +Configure zenith-desk with the network parameters: +``` +:zenith &config-chain-id 'zenith-stage1' +:zenith &config-janus-endpoint 'http://34.169.229.181:8090' +:zenith &config-http-api ['api.zenithd.zenith-test.tlon.systems' '1317'] +:zenith &config-rpc ['api.zenithd.zenith-test.tlon.systems' '26657'] +``` + +Manage accounts and tokens: +``` +# Add account with private key +:zenith &add-account ['my-ship-name' 0x500e.49.....] + +# Query zenith addresses +:zenith &zenith-address [our] +:zenith &zenith-address [~fus] + +# Check balances +:zenith &balances-by-ship ~fipfus + +# Send tokens +:zenith &send-to-ship ['my-ship-name' ~harrus 100 '$sZ'] +``` \ No newline at end of file diff --git a/docs/documentation/watchers.md b/docs/documentation/watchers.md new file mode 100644 index 0000000..0fdf60f --- /dev/null +++ b/docs/documentation/watchers.md @@ -0,0 +1,65 @@ +# Watchers + +Watchers are specialized indexing services that monitor blockchain events and maintain queryable databases. The Zenith ecosystem uses three watchers to track different data sources, each exposing data through GraphQL APIs for application use. + +--- + +## Azimuth Watcher + +Monitors Urbit's Azimuth identity registry on Ethereum, tracking point ownership, sponsorship relationships, and identity state changes. + +**Data Sources**: Ethereum mainnet Azimuth contracts + +**Example Query**: +```graphql +query { + point(id: "~sampel-palnet") { + owner + sponsor + keyRevisionNumber + } +} +``` + +--- + +## Lockdrop Watcher + +Monitors the Zenith lockdrop contract on Ethereum, tracking participant deposits and lock commitments during Stage 0. + +**Data Sources**: Ethereum lockdrop contract + +**Example Query**: +```graphql +query { + deposit(address: "0x...") { + points + lockDuration + timestamp + } +} +``` + +--- + +## Zenith Watcher + +Indexes the Zenith blockchain itself, tracking transactions, account states, and module events. + +**Data Sources**: Zenith blockchain (all stages) + +**Example Query**: +```graphql +query { + account(address: "zenith1...") { + balances { + denom + amount + } + transactions { + hash + timestamp + } + } +} +``` diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..d92b20f --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,164 @@ +# Glossary + +This glossary defines technical terms used throughout the Zenith documentation that may be unfamiliar to the average reader. + +--- + +## A + +### ABCI / ABCI++ +**Application Blockchain Interface** - The interface between the consensus engine (CometBFT) and the application logic in Cosmos SDK blockchains. ABCI++ is an enhanced version that adds features like vote extensions for collecting external data during consensus rounds and optimistic execution for improved performance. + +### Attestation +A cryptographic proof that links an Azimuth point owner's Ethereum address to their Zenith address. Participants submit nested attestations during onboarding, with both Ethereum and Zenith signatures proving ownership and identity. + +### Azimuth +Urbit's identity registry system deployed on Ethereum. It serves as the source of truth for Urbit point ownership, maintaining a hierarchical structure of cryptographic identities (galaxies, stars, and planets). Zenith uses Azimuth as the basis for validator eligibility and network participation. See [Azimuth](documentation/azimuth.md) for detailed information. + +--- + +## B + +### Bundle / Bundling +The process of aggregating multiple individual transactions into a single batch for efficient processing and MEV opportunities. Stars' Janus server collect transactions from Planets and bundle them before submitting to their sponsoring Galaxys' Janus server. + +--- + +## C + +### Comet +The lowest tier in the Urbit identity hierarchy, representing a temporary, disposable identity. Comets have unlimited supply and currently have no specific role in the Zenith network. + +### Consensus +The process by which distributed nodes in a blockchain network agree on the current state of the ledger. Zenith uses Cosmos SDK's Tendermint-based consensus mechanism where validators propose, validate, and finalize blocks. + +### Cosmos SDK +An open-source framework for building custom blockchain applications in Go. It provides modular architecture with pre-built modules for common blockchain features, fast finality, seamless upgrades without hard forks, and extensive developer tools. + +--- + +## E + +### EndBlocker +A lifecycle hook in Cosmos SDK that executes logic at the end of each block. Zenith uses EndBlocker to apply state changes like validator jailing and slashing and ownership transfers after consensus has been reached. + +### ePBS (Enshrined Proposer-Builder Separation) +A protocol-level mechanism that separates the roles of block proposers (who choose which transactions to include) and block builders (who construct the actual blocks). Zenith implements ePBS through a lane-based architecture that ensures fair block space allocation and improves censorship resistance. Stars build bundles from transactions and Galaxies build blocks from bundles. + +--- + +## G + +### Galaxy +The top tier in the Urbit identity hierarchy, limited to exactly 256 total identities. In Zenith, only galaxies can be validators who build blocks and participate in consensus. Galaxy validators must also own an "associated star" (a star sponsored by and owned by the same account as their galaxy). + +### Genesis / Genesis File +The initial state of a blockchain at launch, encoded in a genesis.json file. It contains all starting balances, validator information, and module configurations. Zenith's genesis is created during the Token Generation Event (TGE), following the Stage 0 Lockdrop Onboarding. + +--- + +## J + +### Jailing +A validator punishment mechanism where a validator is removed from the active validator set and stops earning new token rewards. Jailing typically happens together with slashing. In Zenith, validators are automatically jailed when they transfer ownership of their Azimuth point or fail to maintain uptime requirements. + +### Janus +Named after the two-faced Roman god, Janus is the transaction aggregation layer across address space. Stars run Janus to collect transactions from planets, bundle them, and submit to galaxy validators. Galaxy validators run zenithd in validator mode which accepts bundles from both their associated star and independent sponsored stars. Independent star owners run zenithd in star mode which includes the Janus bundling service. + +--- + +## L + +### Lane +A dedicated channel for block construction in Zenith's ePBS implementation. The lane-based architecture splits block space across multiple lanes with different priorities: the associated star lane (15%), sponsored stars lane (75%), and default lane (remaining space). + +### Lockdrop +A token distribution mechanism where participants lock assets (Azimuth points) in a smart contract for a specified duration (1-5 years) to earn rights to initial token allocations. Participation in Zenith's lockdrop guarantees an initial $Z allocation at TGE, with longer lock periods potentially offering greater rewards. Lockdrop participation is not required for operators who join later in Stage 2 to earn $Z through active participation. Simulation tools are available at [lockdrop-simulation](https://github.com/Zenith-Foundation/lockdrop-simulation). + +--- + +## M + +### MEV (Maximal Extractable Value) +The maximum value that can be extracted from block production beyond standard block rewards and transaction fees, typically through transaction reordering, insertion, or censorship. Zenith's ePBS implementation helps distribute MEV more fairly. + +### Moon +A lower-tier identity in the Urbit hierarchy. Each planet can spawn up to 65,535 moons. Moons currently have no specific role in the Zenith network. + +### Module +A self-contained unit of blockchain functionality in the Cosmos SDK architecture. Zenith includes custom modules for onboarding, scry oracle, point tracking, and immutable treasury management, alongside standard Cosmos SDK modules. + +--- + +## O + +### Oracle +A system that brings off-chain data onto the blockchain. Zenith's scry oracle aggregates data from the Urbit network through a decentralized consensus process, making it available for on-chain applications to query. + +--- + +## P + +### Planet +The third tier in the Urbit identity hierarchy. Planets have a sponsorship relationship with stars. In Zenith, planets are the exclusive transaction submitters - only planets can submit transactions to the network. They submit transactions to their sponsoring star's Janus service, which bundles them for galaxy validators. When onboarding to Zenith, planets receive $Z from a faucet operated by their sponsoring star. Planets cannot participate in the lockdrop but are critical network participants starting from Stage 1. + +### Point +A cryptographic identity in the Urbit/Azimuth system. Points come in hierarchical classes (galaxies, stars, planets, moons, comets) and represent ownership of a network identity with specific privileges and responsibilities. + +### Proposer +The validator selected to construct and propose the next block during a consensus round. In Zenith's ePBS system, the proposer follows lane-based rules to ensure fair inclusion of bundles from different stars. + +--- + +## S + +### Scry +In Urbit, a read-only query mechanism for accessing data stored on Urbit ships. Scry paths point to specific pieces of data (e.g., `/~zen/metadata-store/associations/groups/random-group/json`). Zenith's scry oracle stores mappings from scry paths to their data hashes on-chain. + +### Ship +A personal server in the Urbit network, identified by a point. Each ship has a cryptographic identity registered in Azimuth and can communicate with other ships in the network. + +### Slashing +The penalty mechanism where validators lose existing tokens for malicious behavior or failure to meet operational requirements. Slashing is more severe than jailing and typically happens together with it. Slashing is usually the consequence of double-signing. In Zenith, validators face automatic slashing when they transfer their Azimuth point ownership or fail to maintain uptime per the protocol requirements. + +### Sponsorship +The hierarchical relationship in Urbit where higher-tier points sponsor lower-tier points, providing infrastructure and routing services. Sponsorship relationships can be changed via mutual agreement using Bridge. In Zenith, stars submit transaction bundles to their sponsoring galaxy. + +### Stakez +A non-transferable token in Zenith used during Stage 1 for validator mechanics, chain operations, and claiming accrued $Z tokens. In Stage 2, stakez is migrated to Zenith Staking NFTs (ZSN). + +### Star +The second tier in the Urbit identity hierarchy. Stars have a sponsorship relationship with galaxies. In Zenith, stars bundle transactions from planets and send them to galaxy validators. There are two types: "associated stars" owned by galaxy validators whose Janus servers run in-process within zenithd validator mode, and independent stars that run zenithd in star mode (which includes the Janus bundling service). + +--- + +## T + +### TGE (Token Generation Event) +The moment when the full supply of $Z tokens is created and allocated. TGE marks the transition from Stage 0 (onboarding) to Stage 1 (mainnet), includes verification of all attestations, and generates the genesis file for mainnet launch. + +--- + +## V + +### Validator +A node operator responsible for participating in consensus, validating bundles, and producing blocks. In Zenith, only galaxies can be validators. Galaxy validators must also own an associated star (sponsored by and owned by the same account as their galaxy) whose Janus server runs in-process within zenithd. + +### Vote Extension +An ABCI++ feature that allows validators to attach additional data to their votes during consensus rounds. Zenith uses vote extensions to collect external data (e.g., scry bindings) before reaching consensus. + +--- + +## Z + +### zenithd +The main blockchain daemon (server software) for the Zenith network. Built on Cosmos SDK, zenithd includes custom modules for onboarding, oracle functionality, point tracking, and treasury management, plus a built-in Janus server for accepting transaction bundles. + +### znt (Zenith Onboarding Token) +A utility token used exclusively during Stage 0 for making transactions on the Stage 0 zenithd testnet. Delivered via faucet in the onboarding application, znt has no monetary value and is used solely for transaction fees during the onboarding phase. + +### ZSN (Zenith Staking NFT) +Tradable NFTs introduced in Stage 2 that represent validation and bundling rights. Each stakez position converts 1:1 to a corresponding ZSN, with galaxies receiving validator rights NFTs and stars receiving bundling rights NFTs. ZSNs add economic weight to Urbit's sponsorship relationships. + +### $Z +The native token of the Zenith blockchain, used for transaction fees, governance, and as the base currency for the network. $Z is distributed to lockdrop participants based on their committed Azimuth points and network participation, with vesting schedules determined by individual cliff dates. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..db02859 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,54 @@ +# Zenith Documentation + +Welcome to the official documentation for the Zenith blockchain ecosystem. Zenith is a specialized Cosmos SDK blockchain that bridges the Urbit ecosystem with blockchain consensus, enabling Azimuth point owners to participate in decentralized governance while maintaining their network identity. + +## Quick Start + +- **New to Zenith?** Start with the [Introduction to Zenith](overview/introduction.md) +- **Looking to participate?** Check out [Lockdrop Onboarding](overview/lockdrop-onboarding.md) +- **Want to develop?** See [App Development](documentation/app-development.md) +- **Need commands?** Browse the [Command Reference](command-reference/index.md) + +## What is Zenith? + +Zenith creates a unique bridge between the Urbit network and blockchain technology: + +- **Identity Preservation**: Your Urbit network identity is maintained on the blockchain +- **Ownership Verification**: Only verified owners of Azimuth points can participate in consensus +- **Decentralized Governance**: Urbit community members participate in blockchain governance +- **Scry Oracle**: Aggregates off-chain data from the Urbit network for on-chain use + +## Core Components + +### Blockchain Infrastructure +- **zenithd**: Main Zenith blockchain node with custom Cosmos SDK modules +- **Janus**: Transaction aggregation layer bridging Urbit ships and the blockchain +- **Scry Oracle**: Decentralized oracle system for off-chain data aggregation + +### User Interfaces +- **Onboarding App**: Web interface for Azimuth point owners to register and participate +- **Zenith Wallet**: Web-based wallet service for managing Zenith accounts +- **Block Explorers**: Tools for exploring transactions and network activity + +### Supporting Services +- **Azimuth Watcher**: Monitors Azimuth point ownership on Ethereum +- **Zenith Faucet**: Distributes tokens during onboarding stages + +## Network Stages + +Zenith operates through a carefully orchestrated multi-stage process: + +1. **Stage 0**: Onboarding phase where Azimuth point owners register and provide attestations +2. **Token Genesis Event (TGE)**: Verification phase where all attestations are validated +3. **Stage 1**: Production blockchain launch with verified participants as validators + +## Getting Help + +- **Source Code**: All Zenith project codebases are available at [github.com/Zenith-Foundation](https://github.com/Zenith-Foundation) +- **Documentation Issues**: Report problems with these docs on [GitHub](https://github.com/Zenith-Foundation/zenith-docs) +- **Technical Support**: Join the community discussions +- **Development Questions**: Check the [Command Reference](command-reference/index.md) and code repositories + +--- + +*These docs are actively maintained by the Zenith development team. Last updated: {{ git_revision_date_localized }}* diff --git a/docs/overview/index.md b/docs/overview/index.md new file mode 100644 index 0000000..8cd19b2 --- /dev/null +++ b/docs/overview/index.md @@ -0,0 +1,24 @@ +# Overview + +This section provides a comprehensive introduction to the Zenith blockchain ecosystem, covering the fundamental concepts, participation models, and key responsibilities within the network. + +## Getting Started + +**New to Zenith?** Start with the [Introduction to Zenith](introduction.md) to understand core concepts and technical architecture. + +**Ready to participate?** Learn about [Lockdrop Onboarding](lockdrop-onboarding.md) to join the network launch. + +**Want to understand your role?** See [Roles & Responsibilities](roles-responsibilities.md) for detailed requirements by participant type. + +## Key Concepts + +### Urbit-Blockchain Bridge +Zenith creates a unique connection between the Urbit network and blockchain technology, allowing Azimuth point owners to participate in consensus while maintaining their network identity. + +### Two-Stage Network Launch +The network launches through a carefully orchestrated process: +1. **Stage 0**: Registration and attestation collection +2. **Stage 1**: Production blockchain with verified validators + +### Ownership Verification +All participants must cryptographically prove ownership of their claimed Azimuth points through the Azimuth registry on Ethereum. \ No newline at end of file diff --git a/docs/overview/introduction.md b/docs/overview/introduction.md new file mode 100644 index 0000000..ef9aeea --- /dev/null +++ b/docs/overview/introduction.md @@ -0,0 +1,57 @@ +# Introduction to Zenith + +Zenith bridges Urbit's Azimuth PKI from Ethereum to a sovereign Cosmos chain. It enables Galaxy and Star owners' economic participation in the network as operators with defined roles. Planets participate as users that submit transactions to their sponsoring Star. Zenith's unique combination of features enables + +## Background + +### Urbit + +[Urbit](https://urbit.org) is a decentralized computing platform with that empowers users with permanent personal servers. Each user owns a cryptographic identity called a "point", an ERC-721 token in the Azimuth registry on Ethereum. The Azimuth registry serves as the source of truth for point ownership, enabling cryptographic verification of identity claims without relying on external identity providers. **Reliance on Ethereum brings challenges and limitations to Urbit that are addressed by Zenith.** + + +Urbit points come in hierarchical classes (Galaxies, Stars, Planets) that form a sponsorship network. In Zenith, galaxies serve as validators while stars bundle transactions from planets. Planets are the exclusive transaction submitters on the network. See [Roles & Responsibilities](roles-responsibilities.md) for details on each participant type. + +### The Cosmos SDK Foundation +Zenith is built on the [Cosmos SDK](https://cosmos.network/sdk), which provides a modular architecture for core features like token management, staking, and governance. It focuses on security, scalability, and ease of development, offering quick transaction finality with mature consensus mechanisms and seamless protocol upgrades without hard forks. The SDK also comes with extensive developer tools and strong community support. + +Zenith leverages this flexibility and security to tailor a network specifically for Urbit's community, combining blockchain consensus with Urbit's unique identity system. + + +### Why Bridge Urbit and Blockchain? + +Traditional blockchain governance often suffers from fundamental challenges including Sybil attacks where fake identities can manipulate governance, plutocratic governance where wealth concentration leads to power concentration, lack of meaningful and persistent identity verification systems, and low governance participation due to complexity or disengagement. + +Zenith solves these problems by creating a unique bridge. Only verified Azimuth point owners can participate in governance, providing proven identity. The system maintains Azimuth-based cryptographic identity verification for decentralized identity, leverages existing Urbit sponsorship relationships to preserve social structure, and adds economic consequences to Urbit network participation for better alignment. + +## Core Components + +### zenithd + +The main daemon contains four custom modules. The Onboarding Module manages participant enrollment and attestation validation (during the lockdrop). The Scry Oracle Module aggregates off-chain data using ABCI++ vote extensions. The Zenith Module tracks Azimuth point ownership and handles validator jailing and slashing. The Immutable Treasury Module manages $Z distribution and vesting. + +### Janus + +Named after the two-faced Roman god, Janus faces both directions: toward Urbit ships and toward the Zenith consensus layer. + +**Architecture**: `Planet → Star → Galaxy` + +Star nodes collect transactions from sponsored planets, bundle transactions and batch scry bindings, then submit directly to their sponsoring Galaxy. + +### Scry Oracle + +A decentralized oracle aggregates off-chain data from the Urbit network. Validators collect external data via vote extensions, including Ethereum heights, ownership changes, and scry bindings. Consensus aggregates and validates data before storing it on-chain, allowing applications to query this data through standard blockchain APIs. + +### Azimuth Integration + +Continuous monitoring of Azimuth point ownership occurs through the Azimuth Watcher, which tracks ownership changes in real-time, provides cryptographic proof of point ownership, and enables automatic validator jailing and slashing on point transfers. + +## Participation Details + +Zenith participation requires ownership of Azimuth points registered in the Ethereum Azimuth registry. Galaxy owners can become validators, while star owners participate as transaction bundlers. All participants must complete the lockdrop onboarding process and provide cryptographic attestations linking their Azimuth identity to their Zenith account. + +The network maintains security through automatic jailing and slashing when validators transfer point ownership and progressive penalties if external data updates stall. See [Roles & Responsibilities](roles-responsibilities.md) for detailed requirements and [Lockdrop Onboarding](lockdrop-onboarding.md) for the participation process. + + +## Next Steps + +Learn about the [Lockdrop Onboarding](lockdrop-onboarding.md) process, understand [Roles & Responsibilities](roles-responsibilities.md) in the network, and explore the [Network Stages](../documentation/network-stages.md) in detail. diff --git a/docs/overview/lockdrop-onboarding.md b/docs/overview/lockdrop-onboarding.md new file mode 100644 index 0000000..962b6f6 --- /dev/null +++ b/docs/overview/lockdrop-onboarding.md @@ -0,0 +1,121 @@ +# Lockdrop Onboarding + +The lockdrop onboarding process is the critical mechanism through which Azimuth point owners commit to the Zenith network and secure their initial $Z token allocation. This process occurs during Stage 0 and determines eligibility for the initial token distribution at TGE. + +!!! warning "Initial Allocation Requirement" + Participating in the lockdrop **guarantees an initial $Z allocation** at TGE. However, lockdrop participation is **not required** to earn $Z as a network operator once that feature is enabled in Stage 2. Operators who join later can still earn $Z through active participation, but will not receive initial allocation. + +## Overview + +The lockdrop serves multiple purposes. It demonstrates real economic commitment to network success, secures initial $Z token allocation at TGE, links Azimuth point ownership to Zenith participation, and creates the initial economic foundation for the network. + +### Contract Details +The repository is available at [zenith-lockdrop](https://github.com/Zenith-Foundation/zenith-lockdrop). The testnet deployment is on [Sepolia](https://sepolia.etherscan.io/address/0xa41a0d99Fc44BA544348569a5A5AaCa998302886#code), and the mainnet contract will be deployed when Stage 0 begins following a professional security audit. + +#### Point Ownership +Participants must own the required Azimuth points registered in the Ethereum Azimuth registry. See [Roles & Responsibilities](roles-responsibilities.md) for specific ownership requirements by participant type. + +#### Lockdrop Participation +Participants must deposit their owned Azimuth points into the lockdrop contract and choose a commitment duration between 1-5 years, which affects future reward multipliers. This demonstrates real commitment through economic risk, and points cannot be withdrawn until the commitment period ends. + +#### Attestation Submission +Participants must provide both Ethereum and Zenith cryptographic signatures as proof of point ownership. This links Azimuth identity to a Zenith account and must be submitted during the 6-month Stage 0 period. + +## Participation Process + +### Step 1: Prepare for Onboarding + +#### Verify Point Ownership +```bash +# Verify your points in Azimuth registry +# Check ownership status and any restrictions +``` + +#### Set Up Wallets +Participants need an Ethereum wallet (MetaMask or hardware wallet) with point control and a new Zenith account for blockchain participation. Secure backup of all cryptographic keys is essential. + +### Step 2: Lockdrop Participation + +#### Access Onboarding Application +The onboarding application is available at [onboarding.zenith-test.tlon.systems](https://onboarding.zenith-test.tlon.systems/) and requires a modern web browser with wallet support. Participants must be connected to Ethereum mainnet (or Sepolia for testing). + +#### Connect Wallets +1. **Connect Ethereum Wallet**: Connect wallet containing your Azimuth points +2. **Auto-Generate Zenith Account**: App automatically creates Zenith account +3. **Point Detection**: App fetches your owned points from live Azimuth watcher +4. **Selection**: Choose which points to commit to lockdrop + +#### Create Attestations +The onboarding process creates a nested attestation structure: + +``` +┌────────────────────────────────────────────────────────┐ +│ ATTESTATION STRUCTURE │ +├────────────────────────────────────────────────────────┤ +│ Outer Layer (Zenith Signature): │ +│ ┌───────────────────────────────────────────────────┐ │ +│ │ Zenith Payload: │ │ +│ │ • zenith_address: zenith1j66ujjcuv2l4d... │ │ +│ │ • message: "Onboarding my validator..." │ │ +│ │ • ethereum_payload: ┌───────────────────────────┐ │ │ +│ │ │ Inner Layer (ETH Sig): │ │ │ +│ │ │ • eth_address: 0x5dc6... │ │ │ +│ │ │ • msg: "Onboarding..." │ │ │ +│ │ │ • owned_points: │ │ │ +│ │ │ - galaxy: "~byt" │ │ │ +│ │ │ - stars: ["~mipbyt"] │ │ │ +│ │ └───────────────────────────┘ │ │ +│ └───────────────────────────────────────────────────┘ │ +│ Signatures: │ +│ • Zenith Signature: xv6BkXuB03uCMS9QLHsS... │ +│ • ETH Signature: 0x1621de2ce664a7e201e43bae... │ +└────────────────────────────────────────────────────────┘ +``` + +### Step 3: Blockchain Submission + +#### Submit to Stage 0 Chain +Attestations are submitted to the single Tlon-operated zenithd validator, with gas fees paid using znt tokens from a faucet. Participants receive transaction confirmation on the testnet, and attestations are stored on the Stage 0 blockchain for later verification. + +#### Verification Status +Stage 0 accepts all attestations with limited verification, collecting all submissions for later processing. Full verification occurs during TGE between Stage 0 and Stage 1. + +## Critical Timing and Deadlines + +### Stage 0 Duration +The Stage 0 phase lasts 6 months from lockdrop contract deployment, and participants must complete onboarding within this period. There is a hard deadline with no extensions for late participation. + +## Economic Implications + +### Initial Token Allocation Rights +Lockdrop participation directly determines initial $Z allocation at TGE. Galaxy owners (who must also own an associated star) are eligible for validator allocations, while star-only participants are eligible for bundler allocations. Longer commitments may receive allocation bonuses, with each participant's share determined relative to total network participation. + +!!! info "Future Operator Participation" + Starting in Stage 2, operators can join the network and earn $Z through active participation even without lockdrop participation. However, they will not receive the initial allocation reserved for lockdrop participants. + +### Future Value Accrual +Different participant types earn tokens differently. Galaxies earn through active block validation, stars earn through transaction bundling services, and service providers earn additional tokens through optional network services. All participants need $Z to pay transaction fees. + +## Verification Process (Between Stages) + +### What Gets Verified +During TGE, all Stage 0 attestations undergo rigorous verification: + +1. **Signature Verification**: Both Ethereum and Zenith signatures verified +2. **Point Ownership**: Claimed points verified against live Azimuth registry +3. **Lockdrop Status**: Lockdrop participation confirmed on Ethereum L1 +4. **Data Integrity**: All attestation data checked for consistency + +### Verification Outcomes +Verified participants proceed to Stage 1 with initial token allocations, while those who fail verification are excluded from the initial $Z allocation. Verification is final with no appeals or second chances, and failed participants lose their lockdrop commitments and initial allocation rights. However, they may still join as operators in Stage 2 to earn $Z through active participation. + +## Testing and Simulation + +### Lockdrop Simulation +Comprehensive simulation tools are available at [lockdrop-simulation](https://github.com/Zenith-Foundation/lockdrop-simulation) that allow participants to test the complete lockdrop workflow without real assets. These tools cover the full network lifecycle from Stage 0 through Stage 1, enabling developers and participants to practice the process and understand how different lockdrop durations (1-5 years) affect their allocations. + +### Testnet Environment +The contract is available on the Ethereum Sepolia testnet where participants can use test Azimuth points for practice. This provides safe testing with no real economic value at risk, allowing users to validate their understanding before mainnet. + +!!! success "Next Steps" + After completing lockdrop onboarding, participants wait for TGE where their attestations are verified and they receive initial $Z allocations if verification succeeds. See [Network Stages](../documentation/network-stages.md) for what happens next. diff --git a/docs/overview/roles-responsibilities.md b/docs/overview/roles-responsibilities.md new file mode 100644 index 0000000..10af295 --- /dev/null +++ b/docs/overview/roles-responsibilities.md @@ -0,0 +1,90 @@ +# Roles & Responsibilities + +The Zenith network defines specific roles and responsibilities for different types of Azimuth point owners. Each participant type has distinct technical requirements and economic incentives. + +## Galaxies (Validators) + +Only galaxies can be validators on Zenith. Galaxy owners must also own an "associated star" (a star sponsored by and owned by the same account as their galaxy) to participate as validators. This dual ownership model ensures both governance authority through the galaxy and operational transaction bundling through the associated star. + +### Ownership Requirements +Validators must own a galaxy (1 of 256 total) in the Azimuth registry along with an associated star sponsored by that galaxy and owned by the same account. Both points must be deposited in the Ethereum L1 lockdrop contract, and validators must provide cryptographic proof of ownership for both points. + +### Operational Role +Galaxies are the only validators on Zenith - they build blocks and participate in consensus. The associated star's Janus server runs in-process within zenithd and bundles transactions from sponsored planets, submitting those bundles directly to the galaxy validator which puts them into blocks. Independent stars (not associated with a galaxy) bundle transactions from planets and send those bundles to galaxy validators over HTTP. + +### Stage 1 Responsibilities +Validators must operate a full `zenithd` validator node with consensus participation, which includes the associated star's Janus server running in-process. They must maintain self-hosted Urbit ships for both their galaxy and associated star points. They actively sign blocks to earn $Z accrual and meet technical requirements for reliable validator operations. + +### $Z Token Accrual +Validators must actively sign blocks to earn token accrual. Accrual is performance-based and tied to successful block production and network participation. Jailing and slashing serve as penalties—jailing stops new token accrual until the issue is resolved, while slashing causes loss of existing tokens. Validators must maintain control of both their galaxy and associated star points to continue earning. + +## Stars (Bundlers) + +Star owners who are not also galaxy validators participate as independent bundlers, aggregating transactions from planets and submitting them to galaxy validators. These are distinct from the "associated stars" that galaxy validators must own, whose Janus servers run in-process with zenithd in validator mode. + +### Ownership Requirements +Independent star operators must own a star point in the Azimuth registry and deposit it in the lockdrop contract. They must provide cryptographic proof of star ownership. Stars have a sponsorship relationship with a galaxy. + +### Operational Role +Independent star operators run zenithd in star mode which includes the Janus bundling service to collect transactions from planets they sponsor. They bundle these transactions and submit the bundles to galaxy validators over HTTP. Stars typically submit bundles to their sponsoring galaxy, maintaining the Urbit sponsorship relationship. They contribute to network efficiency through transaction bundling and can optionally run additional services for extra $Z rewards. + +### Stage 1 Responsibilities +Independent star operators must run zenithd in star mode (which includes the Janus bundling service) to aggregate transactions and maintain a self-hosted Urbit ship for their star point. They collect transactions from planets they sponsor and submit bundles to galaxy validators over HTTP. Optionally, they can run additional services to earn extra $Z, including indexer services, application hosting, data aggregation services, and network monitoring. + +### $Z Token Accrual +Star operators must actively bundle and submit transactions to their sponsoring galaxy to earn rewards. They earn rewards from bundling transaction fees and receive additional bonuses for running optional network services. + +## Planets (Transaction Submitters) + +Planets are critical participants in the Zenith network starting from Stage 1. They are the only entities that can submit transactions to the network, making them essential for network activity and usage. + +### Ownership Requirements +Planet owners must own a planet point in the Azimuth registry. Planets are sponsored by a star, which provides their connection to the network infrastructure. + +### Operational Role +Planets are the exclusive transaction submitters on Zenith. Only planets can submit transactions to the network. They submit transactions to their sponsoring star's Janus service, which bundles them and forwards them to galaxy validators. Planets use the network for applications, services, and all transaction activity. + +### Lockdrop Participation +Planet holders cannot participate in the Stage 0 lockdrop process and will not receive initial $Z allocations at TGE. However, during Stage 0, planets can participate in a parallel testnet by signing up to the Tlon App where they receive fake $Z tokens for testing purposes. + +### Onboarding and $Z Acquisition +When onboarding to Zenith, planets receive $Z from a faucet operated by their sponsoring star. This provides them with the tokens needed to pay transaction fees and participate in network activity. Planets acquire $Z through: +- Initial faucet distribution from their sponsoring star during onboarding +- Purchasing $Z from market makers or other participants +- Earning through application usage and network participation + +### Stage 1 Participation +Planets are active network participants starting from Stage 1 launch. They submit all network transactions, interact with Zenith-enabled applications and services, pay transaction fees in $Z, and participate in the network economy through their sponsoring star. + +## Moons & Comets + +Currently, moons and comets have no specific enshrined role in the Zenith system. + +### Future Opportunities +Moons and comets may have potential future roles in economic participation pending community and developer interest. They may participate in the ecosystem through application usage and could have possible future inclusion in governance mechanisms. + +!!! note "Evolving Roles" + The roles of moons and comets may expand as the Zenith ecosystem develops and the community expresses interest in broader participation models. + +## Economic Incentives + +### Galaxy Rewards +Galaxies earn validator rewards from block production, transaction fees from network activity, and block rewards from consensus participation. + +### Star Rewards +Stars earn transaction bundling fees, optional service revenue from activities like indexing and hosting, and rewards for aggregation services. + +### Planet Benefits +Planets are the exclusive transaction submitters on the network, providing essential network activity. They receive initial $Z from their sponsoring star's faucet during onboarding, gain access to Zenith applications and services, participate in Urbit-native decentralized applications, and benefit from lower transaction costs through star bundling and aggregation. + +## Technical Requirements + +### Infrastructure Requirements +Galaxies require zenithd running in validator mode with high availability and substantial bandwidth. The associated star's Janus server runs in-process within zenithd validator mode. Independent stars run zenithd in star mode (which includes the Janus bundling service) with moderate infrastructure requirements. Planets require only a basic Urbit ship with minimal technical requirements. + +### Connectivity Requirements +Galaxies maintain direct connections to the consensus network and receive bundles from independent stars. Associated stars' Janus servers run in-process and don't require external connectivity. Independent stars connect to galaxy validators to submit bundles and to planets via the Urbit network. Planets connect to their sponsoring star via the Urbit network to submit transactions. + +## Next Steps + +Ready to participate? Learn about the [Lockdrop Onboarding](lockdrop-onboarding.md) process to join the Zenith network. \ No newline at end of file diff --git a/docs/public-infrastructure.md b/docs/public-infrastructure.md new file mode 100644 index 0000000..9ecf6b6 --- /dev/null +++ b/docs/public-infrastructure.md @@ -0,0 +1,40 @@ +# Public Infrastructure + +This page provides links and information about the publicly available Zenith testnet infrastructure components for developers and users. + +## Testnet Services + +The following services are available on the Zenith testnet for development, testing, and demonstration purposes: + +| Service | URL | Description | +|---------|-----|-------------| +| **Onboarding Application** | [onboarding.zenith-test.tlon.systems](https://onboarding.zenith-test.tlon.systems/) | Web interface for Azimuth point owners to register and submit attestations. Includes Ethereum wallet connection, point selection/verification, and cryptographic attestation creation. | +| **`zenithd` RPC Node** | [zenithd.zenith-test.tlon.systems](https://zenithd.zenith-test.tlon.systems/) | Direct blockchain node access with REST API, gRPC interfaces, and WebSocket connections for application development and queries. | +| **Token Faucet** | [faucet.zenith-test.tlon.systems/faucet](https://faucet.zenith-test.tlon.systems/faucet) | Distribute free test tokens for transaction fees during development (rate limited). | +| **Block Explorer** | [explorer.zenith-test.tlon.systems](https://explorer.zenith-test.tlon.systems/) | Browse blockchain transactions, blocks, and network activity. Search transactions, view block information, check account balances, and monitor network statistics. | +| **Web Wallet** | [wallet.zenith-test.tlon.systems](https://wallet.zenith-test.tlon.systems) | Web-based wallet for managing Zenith accounts, token transfers, and transaction history. | + +## Urbit Infrastructure + +The following Urbit infrastructure services are relevant for Zenith participants: + +| Service | URL | Description | +|---------|-----|-------------| +| **Bridge** | [bridge.urbit.org](https://bridge.urbit.org) | Web interface for managing Azimuth points, including ownership transfers and sponsorship changes. Used to manage galaxies, stars, and planets that participate in Zenith. | +| **Urbit Network Explorer** | [network.urbit.org](https://network.urbit.org) | View the Urbit network structure, point relationships, and Azimuth registry information. | + +## Network Information + +### Testnet Characteristics +- **Network Type**: Stage 0 testnet for development and demonstration +- **Chain ID**: `zenith-testnet-stage0` (verify with RPC node) +- **Token Denomination**: Test tokens for transaction fees +- **Consensus**: Single validator operation (centralized for testing) + +### Availability and Reliability +- **Uptime**: Best effort availability for development purposes +- **Data Persistence**: Testnet data may be reset periodically +- **Support**: Community support through development channels + +!!! warning "Testnet Notice" + These services are provided for testing and development purposes only. Do not use real assets or rely on this infrastructure for production applications. Data may be reset without notice. \ No newline at end of file diff --git a/docs/tokenomics/index.md b/docs/tokenomics/index.md new file mode 100644 index 0000000..2354780 --- /dev/null +++ b/docs/tokenomics/index.md @@ -0,0 +1,94 @@ +# Tokenomics + +The Zenith network employs multiple tokens across different stages of its evolution, each serving specific purposes in the network's transition from testnet to fully sovereign blockchain. + +## Token Overview + +The Zenith ecosystem uses four distinct tokens across three network stages: + +| Token | Stage | Purpose | Transferable | Value | +|-------|-------|---------|--------------|-------| +| **znt** | Stage 0 | Onboarding operations | ✅ | None | +| **stakez** | Stage 1 | Validator mechanics, chain operations | ❌ | None | +| **$Z** | Stage 1 onward | Native currency, fees, governance | ✅ | Yes | +| **ZSN** | Stage 2 onward | Staking/bundling rights NFT | ✅ | Yes | + +--- + +## Zenith Onboarding Token (znt) + +The **znt** token is exclusively used during Stage 0 (the 6-month testnet phase) to enable users to make transactions on the Stage 0 zenithd testnet. It has no dollar value and functions purely as a utility token. Tokens are distributed on demand via faucet in the onboarding application and are freely transferable within Stage 0. The znt token pays for gas fees during transactions on the testnet, allows participants to submit attestations on-chain to prove ownership, and enables participants to verify testnet functionality before mainnet launch. + +!!! note "Testnet Only" + znt tokens have no monetary value and cannot be exchanged for other tokens. They are delivered via faucet in the onboarding app and exist solely to enable Stage 0 testnet transactions. + +--- + +## Zenith Staking Token (stakez) + +The **stakez** token enables validator mechanics and chain operations during Stage 1 (the initial mainnet phase). It can only be acquired through lockdrop participation, is non-transferable and cannot be traded, and has no monetary value. stakez is required for validator operations and consensus participation, allows participants to submit claim transactions for accrued $Z tokens, and facilitates interactions with chain modules during Stage 1. The stakez token is minted at Stage 1 genesis based on lockdrop participation and is retired and migrated to ZSN tokens in Stage 2. + +--- + +## Zenith Token ($Z) + +### Overview +The **$Z** token is the primary value token of the Zenith network, serving as the native currency, fee token, and governance token. + +### Token Generation and Supply + +The full supply of $Z is created at the Token Generation Event (TGE) during Stage 1 genesis. Initially, 100% of the supply is locked in the lockdrop module and allocated across participant categories including lockdrop participants, team, foundation, and market makers. Every token is accounted for before network launch, ensuring complete transparency. + +### Accrual Mechanisms +Different participant categories earn $Z through different mechanisms: + +#### Galaxies (Validators) + +Galaxy validators earn $Z through active block production and signing. Accrual is earned through successful validation and serves as an incentive for maintaining network security. Jailing and slashing serve as penalties for poor performance or rule violations—jailing removes validators from the active set and stops new token accrual, while slashing causes loss of existing tokens. + +#### Stars (Bundlers) + +Stars earn $Z by bundling transactions from planets and submitting them to galaxy validators. Accrual is earned through active transaction bundling, maintaining their sponsor relationship by submitting bundles to their sponsoring galaxy. They earn rewards for providing bundling services to the network. + +#### Market Makers + +Market makers receive 100% of their allocation unlocked immediately at Stage 1 start. Their purpose is to provide initial liquidity for $Z trading, enabling participants to acquire $Z for fees. They must still claim their allocation from the lockdrop module. + +#### Team + +Team members receive $Z through linear vesting over time with programmable vesting schedules. They can claim their accrued amounts multiple times as tokens vest. + +#### Foundation + +The foundation can claim 50% of the market maker allocation for ecosystem development and governance purposes. For example, if market makers receive 10 $Z, the foundation can claim 5 $Z. These funds support protocol development and community initiatives. + +### Claiming Process + +1. **Accrual**: Tokens accrue in lockdrop module based on role/activity +2. **Claiming**: Participants submit claim transactions anytime +3. **Transfer**: Claimed tokens move to user's Zenith account +4. **Unlocked**: Once in user account, tokens are fully transferable + +### Transaction Fees + +The $Z token is the exclusive currency for transaction fees on Zenith, creating a unified economic model that simplifies network economics. All fees benefit $Z holders and validators through value accrual. Users can acquire $Z from market makers to pay for transaction fees. + +### Governance Rights + +$Z provides governance participation through several mechanisms. Token holders can vote on proposals with voting power weighted by their token holdings, participate in network configuration updates through parameter changes, approve new features and modules through protocol upgrades, and allocate development funds through treasury decisions. + +### Unclaimed Token Handling + +Tokens from jailed and slashed validators and inactive participants remain in the lockdrop module until the situation is resolved. These cases are handled through hardforks or protocol governance, with all decisions made transparently through community governance processes. + +--- + +## Zenith Staking NFTs (ZSN) + +**ZSN** tokens represent the evolution from stakez to a Proof-of-Authority (PoA) system that interoperates with Urbit's sponsorship model. ZSN represents a migration from DPoS to Proof-of-Authority with economic consequences, adding economic weight to Urbit's sponsorship relationships, where staking permissions become tradable NFT assets with prices denominated in $Z. ZSN operates from Stage 2 onward as non-fungible tokens that encode validation or bundling permissions, with each NFT backed by a portion of a galaxy's locked $Z assets and fully transferable and tradable. ZSN distribution is based on the final stakez state from Stage 1, with galaxy owners receiving ZSN encoding validator rights and star owners receiving ZSN encoding bundling rights. Each stakez position maps 1:1 to a corresponding ZSN, preserving all existing rights in NFT form. ZSN enables Zenith to become fully sovereign by eliminating reliance on Ethereum or Azimuth, with rights held as tradable community assets carrying perpetual staking permissions and creating market-driven validator selection through economic incentives. + +--- + +## Stage Evolution Summary + +The token system evolves across network stages as described in [Network Stages](../documentation/network-stages.md). Each stage uses different tokens to support the network's progression from testnet to full sovereignty. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6b3d755 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,101 @@ +site_name: Zenith Documentation +site_description: Documentation for the Zenith blockchain ecosystem - bridging Urbit and blockchain consensus +site_url: https://zenith-docs.readthedocs.io +repo_url: https://github.com/Zenith-Foundation/zenith-docs +repo_name: Zenith-Foundation/zenith-docs + +theme: + name: material + logo: assets/zenith-logo.png + favicon: assets/zenith-logo.png + palette: + # Light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: green + accent: light green + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: green + accent: light green + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.indexes + - navigation.top + - search.highlight + - search.share + - content.code.copy + - content.tabs.link + +extra_javascript: + - https://unpkg.com/mermaid@10/dist/mermaid.min.js + +nav: + - Home: index.md + - Overview: + - overview/index.md + - Introduction to Zenith: overview/introduction.md + - Lockdrop Onboarding: overview/lockdrop-onboarding.md + - Roles & Responsibilities: overview/roles-responsibilities.md + - Documentation: + - documentation/index.md + - Network Stages: documentation/network-stages.md + - Azimuth: documentation/azimuth.md + - Operator Deployments: documentation/deployments.md + - Ship Hosting: documentation/urbit-ship-hosting.md + - Janus Server: documentation/janus.md + - Scry Oracle: documentation/scry-oracle.md + - ePBS: documentation/epbs.md + - App Development: documentation/app-development.md + - Light Contracts: documentation/light-contracts.md + - Watchers: documentation/watchers.md + - Tokenomics: tokenomics/index.md + - API Reference: + - api/index.md + - Zenith Desk: api/zenith-desk-api.md + - zenithd: api/zenithd.md + - Janus: api/janus.md + - Azimuth Watcher: api/azimuth-watcher.md + - Lockdrop Watcher: api/lockdrop-watcher.md + - Zenith Watcher: api/zenith-watcher.md + - Command Reference: + - command-reference/index.md + - zenithd: command-reference/zenithd.md + - urbit: command-reference/urbit.md + - Glossary: glossary.md + - Public Infrastructure: public-infrastructure.md + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - attr_list + - md_in_html + - tables + - toc: + permalink: true + +plugins: + - search + - git-revision-date-localized: + enable_creation_date: false + diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..d41dc1a --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +mkdocs>=1.5.0 +mkdocs-material>=9.0.0 +mkdocs-git-revision-date-localized-plugin>=1.2.0 +pymdown-extensions>=10.0.0 \ No newline at end of file