AegisAI RPC API

Remote Procedure Call (RPC) interfaces are provided by AegisAI validator nodes, enabling AegisAI resource nodes and dApp developers to interact with the AegisAI blockchain network. This section documents all available RPC methods.

submitTask

Description

Submits an AI computation request to the AegisAI network.

Parameters:

• sender (address): Blockchain address of the user or delegate initiating the request.

• nonce (uint64): Sender's unique incrementing nonce to prevent replay attacks and ensure uniqueness.

• schema (bytes): Encoded schema defining how to decode the AI response.

  • The first part is an IPFS CID referencing a file describing the decoding method.

  • The second part encodes specific parameters or keys required by the decoding method.

• targetCount (uint256): Number of resource nodes to target for the computation task.

• prompts (bytes): Encoded data defining the prompts for the AI request.

  • The first part is an IPFS CID referencing a template file describing the prompt structure.

  • The second part encodes parameters or values to populate the template.

• modelOptions (bytes): Encoded data uniquely identifying a specific AI model instance.Typically includes:

  • Model hash (e.g., MD5)

  • Temperature

  • Maximum tokens

  • Top-p

  • Frequency penalty

  • Presence penalty

• SID (bytes32):Unique identifier ensures uniqueness of the generated task hash.

• feeParams (bytes, reserved): Currently unused; reserved for future implementation of computation fee payment parameters.

Returns:

• txHash (bytes32):Hash uniquely identifying the blockchain transaction.

• taskHash (bytes32): Hash uniquely identifying the computation task, emitted as part of the blockchain event after transaction confirmation.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "submitRequest",
  "params": {
    "sender": "0xUserAddress123...",
    "nonce": 15,
    "schema": "0xIPFSCIDplusEncodedKeys...",
    "targetCount": 3,
    "prompts": "0xPromptTemplateCIDplusEncodedValues...",
    "modelOptions": "0xModelHashTempMaxTokens...",
    "SID": "0xUniqueIdentifier..."
  },
  "id": 1
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txHash": "0xTransactionHashabc123...",
    "requestHash": "0xTaskHashUnique123..."
  }
}

Error Response Example:

If invalid parameters (like nonce) are provided, the RPC immediately returns an error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Invalid nonce provided"
  }
}

submitInferenceResult

Description:

Allows a resource node to submit AI response data back to the AegisAI network along with Proof of Inference.

Parameters:

• taskHash (bytes32): Unique identifier of the original AI computation request.

• resourceNode (address): Blockchain address of the resource node submitting the computation result.

• result (bytes): Encoded AI computation response data generated by the resource node.

• proof (bytes): Currently unused; reserved for future inclusion of cryptographic or signature-based proofs verifying computation authenticity and correctness.

Returns:

• result (bool): Returns true if the response was successfully submitted, otherwise false.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "submitResponse",
  "params": {
    "requestHash": "0xRequestHashUnique123...",
    "resourceNode": "0xResourceNodeAddress456...",
    "response": "0xEncodedAIResponseData..."
  },
  "id": 1
}

Example Response (Successful Submission):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

Example Response (Failed Submission):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": false
}

Error Response Example:

If invalid parameters (such as requestHash) are provided, the RPC immediately returns an error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Invalid requestHash provided"
  }
}

submitVerification

Description:

This method will allow resource nodes to submit verification results to confirm the correctness of other resource nodes' computations.

Currently, this function is not implemented, but it is reserved for future integration to enhance computation validation and network security.

Note: More details will be provided when the verification system is introduced.

queryPendingTasks (GET)

Description:

Retrieves a list of pending AI computation tasks.

Query Parameters:

• ResourceAddress (string, required): The blockchain address of the resource node making the query.

• TimeStamp (string, required): A timestamp provided by the querying resource node. The exact use (e.g., for request signing, filtering, preventing replay attacks) should be confirmed by the system's specifications.

Responses:

• 200 OK: Successfully retrieved the list of pending tasks (which might be empty).

  • Content-Type: application/json

  • Body Schema:

    • code (integer): Status code, typically 0 for success.

    • message (string): Status message, typically "success" or an error description if code is non-zero.

    • result (array[object]): An array containing objects, where each object represents a pending task available to the requesting resource node.

      • Task Object Properties:

        • taskHash (string): Unique identifier for the AI computation task.

        • schema (string): Identifier or description of the data schema/type expected for the task result.

        • targetCount (integer): The target number of successful result submissions required for this task.

        • prompts (string): The input data or prompts for the AI model.

        • modelOptions (string): Configuration or options specific to the AI model execution.

        • sender (string): The address that originally requested this computation task.

        • executionInfo (array[object]): Information about previous or ongoing execution attempts related to this task (may be empty if no results submitted yet).

      • Execution Info Object Properties:

        • submitter (string): Address of the resource node that submitted this execution result.

        • result (string): The submitted result data (potentially encoded).

        • proofOfInference (string): Submitted proof data (may be empty or placeholder).

        • txHash (string): Transaction hash associated with this specific result submission.

        • status (integer): Current status code of this specific submission (e.g., pending, verifying, verified, failed).

        • postprocessed (string): Information related to any post-processing applied to the result.

        • verificationInfos (array[object]): Details about verification attempts performed on this submission by verifier nodes.

      • Verification Info Object Properties:

        • verifier (string): Address of the verifier node.

        • valid (boolean): Whether the verifier deemed the submission valid.

        • status (integer): Status code of the verification process by this verifier.

        • txHash (string): Transaction hash associated with this verification action.

        • signature (string): Signature from the verifier related to the verification result.

        • nonce (integer): Nonce associated with the task creation, typically related to the sender's account.

        • feeParams (string): Parameters defining the fees or rewards associated with the task.

        • txHash (string): Transaction hash of the original task creation request on the blockchain.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "queryPendingTasks",
  "params": {}
}

Example Response

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "taskHash": "0xTaskHashUnique123abc...",
      "schema": "text-generation-v1",
      "targetCount": 3,
      "prompts": "{\"prompt\":\"Translate the following English text to French: 'Hello, world!'\"}",
      "modelOptions": "{\"model\":\"gpt-neo-2.7B\", \"temperature\":0.7}",
      "sender": "0xSenderAddressOrigin123...",
      "executionInfo": [
        {
          "submitter": "0xAnotherResourceNodeAddress789...",
          "result": "0xEncodedResultDataFromAnotherNode...",
          "proofOfInference": "0x",
          "txHash": "0xSubmissionTxHash1...",
          "status": 2, // Example: Verified
          "postprocessed": "{\"text\":\"Bonjour, le monde!\"}",
          "verificationInfos": [
            {
              "verifier": "0xVerifierNodeAddressABC...",
              "valid": true,
              "status": 1, // Example: Completed
              "txHash": "0xVerificationTxHash1...",
              "signature": "0xVerifierSignature1..."
            }
          ]
        }
      ],
      "nonce": 42,
      "feeParams": "{\"reward\":\"1000\", \"currency\":\"AEGIS\"}",
      "txHash": "0xOriginalTaskTxHashABC..."
    }
    // ... potentially more task objects
  ]
}

queryTask

Description:

Retrieves the full status and response of an AI computation task for a given requestHash.

Parameters:

• requestHash (bytes32): The unique identifier of the AI computation request.

Returns:

• status (string): Current status of the computation task. Possible values:

  • "submitted"

  • "processing"

  • "completed"

  • "verified"

• response (string or bytes): Encoded AI computation response data generated by the resource node.

• verificationCount (uint256): Number of validators that have verified the result.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "queryTask",
  "params": {
    "requestHash": "0xRequestHashUnique123..."
  },
  "id": 1
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "verified",
    "response": "QmIPFSHashExample...",
    "verificationCount": 5
  }
}

Error Response Example (Invalid requestHash):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "Invalid requestHash"
  }
}

RPC Endpoints Used by Frontend

GET /tx/<tx_hash>

• signer: <evm_address>

• tx_type: “creation” / “inference” / “verification”

• associated_task: <task_hash>

• payload:

  • if tx_type is “creation”，then empty

  • if tx_type is “inference”，then

    • inference_result: <ipfs>

    • proof_of_inference: <ipfs>

  • if tx_type is “verification”，then empty