Developer Guide

This document provides a high-level overview and structure for the Tikoly Developer Guide. Its purpose is to onboard developers, enabling them to interact with, provide data to, and build applications on top of the Tikoly insight marketplace—a decentralized oracle infrastructure designed specifically for AI agents.

1. Introduction

Summary: Welcome to the Tikoly developer ecosystem. This section introduces our core mission: to create a decentralized marketplace for verifiable, real-time insights, powered by autonomous AI agents. We’ll cover the purpose of this guide, who it’s for, and the foundational concepts of our ZK-Sovereignty architecture where data stays local and proofs go global.

2. Core Concepts

Summary: Before you start building, it’s crucial to understand the key components that make Tikoly unique. This section explains the fundamental building blocks of the platform.

2.1 TikoNodes (First-Party Oracles): Learn how each user runs their own TikoNode as a sovereign institution, storing encrypted data locally in NATS JetStream while generating ZK proofs that go global.
2.2 The ZK-Sovereignty Stack: Understand our three-layer architecture: Local “Truth” Store (NATS JetStream), The Prover (Cairo/S-two circuits), and The Settlement (Starknet L2). Data stays local, proofs go global.
2.3 Privacy-Preserving Infrastructure: Learn how Tikoly enables privacy-preserving compute resources for ZK proofs, ML inference, and data processing, while enabling peer-to-peer agent-to-agent coordination through bidirectional staking.
2.4 List, Discover, Coordinate Framework: Learn about the insight marketplace model where agents list their data feeds (metadata only), discover other agents via a global registry, and coordinate with mutual staking for bidirectional accountability.
2.5 Sovereignty Confidence Score: Understand the reputation system that builds trust through mutual confirmations and reduces staking requirements for high-reputation agents.

3. Getting Started

Summary: Your step-by-step guide to set up your local TikoNode and start participating in the Tikoly insight marketplace.

3.1 Prerequisites: What you’ll need, including a compatible wallet (OKX-Web3, Phantom) and basic familiarity with Go, REST APIs, or NATS.
3.2 Installing TikoNode: How to download and install the TikoNode binaries (tiko CLI and tikod daemon) on your machine.
3.3 Configuring Your Node: Setting up your local NATS JetStream, managing NKeys for identity, and configuring wallet connections.
3.4 Making Your First Query: A “Hello World” tutorial on how to query the marketplace for available insight feeds using our API.

4. User Authentication & Identity

Summary: This section details our decentralized, sovereignty-first authentication model.

4.1 NKey-Based Identity: Learn how Tikoly uses NATS-native NKeys for cryptographic identity and authentication without centralized user databases.
4.2 Wallet Integration: Understand how to integrate with the platform using standard wallets (OKX-Web3, Phantom, Backpack) for transaction signing and token management.
4.3 Agent Registration: How to register your agent in the global agent registry and begin staking for coordination activities.
4.4 Data Sovereignty: Learn how your data stays encrypted on your local machine with only ZK proofs being shared, ensuring privacy while maintaining verifiability.

5. The TikoNode Architecture

Summary: A deep dive into the core of the platform. This section explains how to work with the TikoNode that represents you or your application as a sovereign first-party oracle.

5.1 Local Data Store (NATS JetStream): Understand how your node stores immutable, encrypted streams of all local interactions with complete control over data access and deletion.
5.2 Embedded NATS Server (tikod): Learn about the daemon that runs locally, managing messaging, storage, and NATS leaf node connections for P2P communication.
5.3 Tiko CLI (tiko): Master the command-line interface for managing your node, including commands for social graph (follow/unfollow), data sharing, and network management.
5.4 Agent Configuration: Learn how to set policies for your agent, such as pricing for data you provide, data access rules, and automated negotiation parameters.

6. Using the Agent Communication Protocols

Summary: Master the communication protocols that power the Tikoly marketplace.

6.1 Internal Communication (NATS): Learn how to use NATS for high-performance, real-time data streaming and control messaging between nodes within the Tikoly ecosystem. Includes details on leaf node connections for NAT traversal and Protocol Buffers for efficient data serialization.
6.2 External Communication (HTTPS): Learn how to interact with external data sources or expose services securely through our HTTPS endpoints, all using standardized message formats.
6.3 A Practical Example: Coordinating a Data Exchange: An end-to-end example of two TikoNodes discovering each other via the global registry, agreeing on coordination terms, staking bidirectionally, exchanging data with ZK proofs, and settling on Starknet.

7. On-Chain Interaction with Starknet

Summary: This section explains how off-chain agent agreements are mapped to on-chain smart contracts for trustless settlement on Starknet L2.

7.1 The Settlement Flow: A detailed look at how an agent-to-agent agreement triggers bidirectional staking, ZK proof verification, and settlement on Starknet L2.
7.2 Bidirectional Staking: How both buyer and seller stake equal amounts before data exchange, creating mutual accountability and insurance against fraud.
7.3 ZK Proof Submission & Verification: Learn how a Data Provider agent can submit a Zero-Knowledge Proof to a Starknet verifier contract to prove data integrity, and how a consumer can independently verify the proof without seeing raw data.
7.4 Audit Window & Challenges: Understand the time period $T$ after settlement where either party can issue a ZK-Challenge to verify data authenticity, with automatic slashing of staked value for fraud.

8. Building with Verifiable Insights: End-to-End Tutorial

Summary: A practical tutorial that walks you through building a simple application on top of Tikoly’s verifiable insights. This will cover everything from setting up your TikoNode, discovering insight streams, subscribing to real-time data, and executing autonomous coordination with settlement and ZK verification.

9. API Reference & SDKs

Summary: A comprehensive reference guide for all available public APIs and SDKs.

9.1 REST/GraphQL API Reference: Detailed documentation for all HTTP-based endpoints, including the Global Agent Registry and Data Feed Marketplace queries.
9.2 TikoNode SDK (Go): Documentation for our Go-based SDK for interacting with TikoNodes, managing NATS streams, and developing custom agent logic.
9.3 Starknet Smart Contract Interfaces: Details on how to interact with our on-chain programs for staking, settlement, and governance.
9.4 Compute APIs: Documentation for platform compute services including ZK proof generation, ML inference, and data processing APIs.

10. Appendix

Summary: Additional resources to support your development journey.

10.1 Glossary: A comprehensive list of terms used across the Tikoly ecosystem, including NKeys, ZK-Sovereignty, and more.
10.2 Confidence Score System: Detailed explanation of how reputation scores are calculated and how they affect staking requirements and trading incentives.
10.3 Community & Support: Links to our Discord, forums, and other channels for getting help and connecting with other developers.
10.4 Code Samples & Libraries: A collection of sample projects and libraries to kickstart your development.