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

docs mvp

Browse Source
This commit is contained in:
zramsay
2025-11-28 15:34:21 -05:00
committed by zramsay
commit 00424e7cda
34 changed files with 4689 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/documentation/app-development.md
+15
View File
@@ -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.
docs/documentation/azimuth.md
+41
View File
@@ -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
docs/documentation/deployments.md
+47
View File
@@ -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.
docs/documentation/epbs.md
+33
View File
@@ -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.
docs/documentation/index.md
+14
View File
@@ -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
docs/documentation/janus.md
+65
View File
@@ -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
docs/documentation/light-contracts.md
+8
View File
@@ -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.
docs/documentation/network-stages.md
+127
View File
@@ -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.
docs/documentation/scry-oracle.md
+98
View File
@@ -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.
docs/documentation/urbit-ship-hosting.md
+62
View File
@@ -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 <ship-name> -k <keyfile>
```
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']
```
docs/documentation/watchers.md
+65
View File
@@ -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
}
}
}
```