zramsay/zenith-docs
1
0
Fork 0
Code Pull Requests Activity
docs-mvp
zenith-docs/docs/documentation/scry-oracle.md
zramsay 00424e7cda docs mvp
2025-11-28 15:34:21 -05:00

4.7 KiB
Raw Permalink Blame History

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.