Solidity SDK

Overview

Smart contracts cannot make HTTP requests directly. The Assisters Solidity SDK provides:

An on-chain interface your contracts call to request AI completions.
An off-chain oracle worker (Node.js) that listens for request events, calls the Assisters API, and fulfils the response on-chain.

Installation

npm install @assisters-dev/solidity

Or copy the interfaces directly:

forge install assisters-dev/assisters-solidity

Interfaces

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IAssistersOracle {
    /// @notice Request a chat completion from the Assisters API.
    /// @param prompt     The user prompt.
    /// @param model      Model identifier, e.g. "assisters-chat-v1".
    /// @param maxTokens  Maximum tokens in the response (0 = default).
    /// @return requestId Unique identifier for this request.
    function requestCompletion(
        string calldata prompt,
        string calldata model,
        uint32 maxTokens
    ) external payable returns (bytes32 requestId);

    /// @notice Called by the oracle worker to fulfil a request.
    function fulfillCompletion(
        bytes32 requestId,
        string calldata response
    ) external;
}

interface IAssistersConsumer {
    /// @notice Implement this in your contract to receive fulfilled responses.
    function onCompletionFulfilled(
        bytes32 requestId,
        string calldata response
    ) external;
}

Quick Start — Consumer Contract

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@assisters-dev/solidity/contracts/AssistersConsumer.sol";

contract MyAIContract is AssistersConsumer {
    mapping(bytes32 => string) public results;

    constructor(address oracle) AssistersConsumer(oracle) {}

    function askQuestion(string calldata question) external payable {
        bytes32 requestId = requestCompletion(question, "assisters-chat-v1", 256);
        // store requestId → caller mapping if needed
    }

    function onCompletionFulfilled(
        bytes32 requestId,
        string calldata response
    ) internal override {
        results[requestId] = response;
    }
}

Oracle Worker (Node.js)

import { AssistersOracleWorker } from '@assisters-dev/solidity/worker';

const worker = new AssistersOracleWorker({
  rpcUrl: process.env.RPC_URL!,
  oracleAddress: process.env.ORACLE_ADDRESS!,
  oraclePrivateKey: process.env.ORACLE_PRIVATE_KEY!,
  assistersApiKey: process.env.ASSISTERS_API_KEY!,
});

worker.start(); // Listens for CompletionRequested events and fulfils them

Available Contract Methods (AssistersConsumer base)

Method	Description
`requestCompletion(prompt, model, maxTokens)`	Submit an AI request; returns `requestId`
`onCompletionFulfilled(requestId, response)`	Override to handle fulfilled responses
`setOracle(address)`	Update oracle address (owner only)
`withdrawFees()`	Withdraw accumulated oracle fees (owner only)

Available Worker Methods

Method	Description
`worker.start()`	Begin listening for on-chain requests
`worker.stop()`	Stop the listener
`worker.fulfil(requestId, response)`	Manually fulfil a request

Error Handling

// Requests that revert with OracleError are retried by the worker up to 3 times.
// Failed requests emit CompletionFailed(bytes32 requestId, string reason).

event CompletionFailed(bytes32 indexed requestId, string reason);

function onCompletionFailed(bytes32 requestId, string calldata reason) internal virtual {
    // override to handle failures
}

Security Notes

The oracle address is the only account authorised to call fulfillCompletion.
Use payable requests to fund oracle gas fees; set a fee floor in the oracle contract.
Never store sensitive data in on-chain prompts — all calldata is publicly visible.

On this page