Using the SDK

Relevant source files

The following files were used as context for generating this wiki page:

• apps/packages/sdk/src/index.ts (Assumed, not provided in context)
• apps/packages/sdk/src/executor.ts (Assumed, not provided in context)
• apps/packages/sdk/package.json (Assumed, not provided in context)
• ARCHITECTURE.md
• apps/backend/src/starknet/starknet.service.ts
• apps/dojo/README.md
• apps/backend/package.json
• README.md

The OnChainSage SDK is a crucial component designed to facilitate interaction between client applications (like the backend and frontend) and the OnChainSage smart contracts deployed on the Starknet network. It provides a high-level, abstracted API that simplifies on-chain operations, such as managing trading signals, staking, and voting, by handling the complexities of contract calls and data fetching.

The SDK is part of the modular, data-first architecture of the OnChainSage platform. It acts as the primary bridge to the Blockchain Integration layer, ensuring that other services can interact with the Starknet contracts in a standardized and maintainable way. This encourages loose coupling between components and makes it easier for contributors to build features that leverage on-chain functionality without needing deep expertise in Cairo or Starknet's low-level details.

Sources: ARCHITECTURE.md, README.md

Architecture and Core Concepts

The SDK sits between the application logic (e.g., NestJS backend) and the Starknet blockchain. Its main responsibility is to translate application-level requests into Starknet contract invocations and queries.

This diagram illustrates the SDK's position within the system's data flow.

Key Components

The SDK's functionality is primarily encapsulated within a service that manages provider connections, contract loading, and function execution.

Component	Description	Source File
StarknetService	The main class for interacting with Starknet. It initializes the provider, loads contracts, and exposes methods for on-chain actions.	apps/backend/src/starknet/starknet.service.ts
ContractLoader	A utility used internally by the StarknetService to load Starknet contract instances using their address and ABI.	apps/backend/src/starknet/starknet.service.ts:10
Provider	The Starknet provider instance used to communicate with a Starknet node. The node URL is configurable.	apps/backend/src/starknet/starknet.service.ts:16-18

Dependencies

The SDK relies on the official starknet library to handle interactions with the blockchain.

Sources: apps/backend/package.json

Starknet Interaction

The core of the SDK is the StarknetService, which provides methods to interact with the deployed smart contracts.

Sources: apps/backend/src/starknet/starknet.service.ts

Initialization

To use the SDK, it must first be initialized. The StarknetService constructor sets up a Provider connected to a Starknet node (e.g., http://localhost:5050 for local development) and then proceeds to load the necessary contracts.

// apps/backend/src/starknet/starknet.service.ts:14-21
constructor() {
    // Initialize provider based on environment (Katana local devnet)
    this.provider = new Provider({
      nodeUrl: config.starknet.nodeUrl || 'http://localhost:5050',
    });

    this.contractLoader = new ContractLoader(this.provider);
    this.initializeContracts();
}

The initializeContracts method loads the postSystemContract and badgeSystemContract using their configured addresses and ABIs.

Sources: apps/backend/src/starknet/starknet.service.ts:14-36

Core Functions

The service exposes several methods for interacting with the platform's on-chain features. These functions are asynchronous and return a transaction hash upon successful invocation.

createPost(author: string, content: string)

Creates a new post on-chain by calling the create_post function on the PostSystem contract.

The following diagram shows the sequence of a createPost call.

votePost(postId: string, vote: number)

Submits a vote on an existing post by calling the vote_post function on the PostSystem contract.

Sources: apps/backend/src/starknet/starknet.service.ts:71-86

awardBadge(user: string, badge: string)

Awards a specific badge to a user by invoking the award_badge function on the BadgeSystem contract.

Sources: apps/backend/src/starknet/starknet.service.ts:92-107

getUserData(address: string)

Retrieves a user's forum data and badges by querying the Torii indexer endpoint. Torii provides indexed data from the Starknet contracts.

Sources: apps/backend/src/starknet/starknet.service.ts:113-128

Other Financial Functions

The service also includes mock implementations for payment-related functionalities, which would interact with STRK token contracts.

Function	Description
deposit(walletAddress, amount)	Handles user deposits.
upgradeTier(walletAddress)	Manages user subscription tier upgrades.
payForCall(walletAddress, amount)	Processes payment for specific API calls.
getBalance(walletAddress)	Retrieves a user's token balance.
transfer(sender, recipient, amount)	Executes a token transfer.

Sources: apps/backend/src/starknet/starknet.service.ts:130-174

Dojo Smart Contracts Integration

The underlying smart contracts are built using the Dojo framework, a full-stack toolchain for building on-chain games and autonomous worlds on Starknet. The SDK provides a developer-friendly interface to the models and systems defined in the OnChain Sage Dojo world.

Sources: apps/dojo/README.md, ARCHITECTURE.md

Dojo Models

Models in Dojo define the data structures stored on-chain. The SDK allows applications to query and interact with data related to these models.

Model	Description
Signal	Stores trading signal data (e.g., token, buy/sell, confidence score).
Stake	Tracks user stakes on signals, including the user address and STRK amount.
ValidationVote	Records community votes on a signal's credibility.
UserReputation	Manages user reputation scores based on their validation accuracy.

Sources: ARCHITECTURE.md

Dojo Systems

Systems contain the logic that modifies the state of the models. The SDK's functions (e.g., createPost, votePost) are high-level wrappers around calls to these systems.

System	Description
SignalManager	Registers new signals and updates signal metadata.
StakingSystem	Allows users to stake STRK on signals and tracks stakes.
ValidationSystem	Manages community validation votes and adjusts user reputation.

Sources: ARCHITECTURE.md