JSON-RPC API

We kept the JSON-RPC interface fully Ethereum-compatible so your existing tools just work. Citrate exposes a JSON-RPC 2.0 interface that is fully compatible with standard Ethereum tooling while extending the protocol with AI-native and GhostDAG-specific methods under the citrate_ namespace.

Connection

The default JSON-RPC endpoint is:

http://localhost:8545

All requests use POST with Content-Type: application/json. The request body follows the JSON-RPC 2.0 specification:

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": [],
  "id": 1
}

Chain IDs

Network	Chain ID
Devnet	1337
Testnet	42069

Standard Ethereum Methods

Citrate supports the full set of standard Ethereum JSON-RPC methods. The most commonly used are listed below.

eth_chainId

Returns the current chain ID as a hex-encoded integer.

// Request
{ "jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 1 }
 
// Response
{ "jsonrpc": "2.0", "result": "0x539", "id": 1 }

eth_blockNumber

Returns the number of the most recent block.

// Request
{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }
 
// Response
{ "jsonrpc": "2.0", "result": "0x4b7", "id": 1 }

eth_getBalance

Returns the balance of a given address in wei.

// Request
{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": ["0xABCDEF1234567890abcdef1234567890ABCDEF12", "latest"],
  "id": 1
}
 
// Response
{ "jsonrpc": "2.0", "result": "0x56bc75e2d63100000", "id": 1 }

eth_sendRawTransaction

Submits a signed transaction to the network for inclusion in a block.

// Request
{
  "jsonrpc": "2.0",
  "method": "eth_sendRawTransaction",
  "params": ["0xf86c...signed_tx_data"],
  "id": 1
}
 
// Response
{ "jsonrpc": "2.0", "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", "id": 1 }

eth_call

Executes a message call immediately without creating a transaction on the blockchain.

// Request
{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "params": [
    {
      "to": "0xContractAddress",
      "data": "0xabcdef..."
    },
    "latest"
  ],
  "id": 1
}

eth_estimateGas

Generates an estimate of the gas required for a transaction to complete.

// Request
{
  "jsonrpc": "2.0",
  "method": "eth_estimateGas",
  "params": [
    {
      "from": "0xSenderAddress",
      "to": "0xRecipientAddress",
      "value": "0xde0b6b3a7640000"
    }
  ],
  "id": 1
}
 
// Response
{ "jsonrpc": "2.0", "result": "0x5208", "id": 1 }

Other Supported Methods

eth_getTransactionByHash ... retrieve a transaction by its hash
eth_getTransactionReceipt ... retrieve the receipt of a completed transaction
eth_getLogs ... return logs matching a filter
eth_getCode ... return the bytecode at an address
eth_getStorageAt ... return the value from a storage position
eth_gasPrice ... return the current gas price in wei
net_version ... return the current network ID
net_listening ... return whether the node is listening for connections
web3_clientVersion ... return the current client version

Custom Citrate Methods

The citrate_ namespace provides methods for AI model management, GhostDAG queries, and zero-knowledge proof operations.

citrate_deployModel

Deploys an AI model to the on-chain model registry.

// Request
{
  "jsonrpc": "2.0",
  "method": "citrate_deployModel",
  "params": [{
    "name": "sentiment-v1",
    "format": "onnx",
    "modelHash": "0xabc123...",
    "storageUri": "ipfs://Qm...",
    "inputSchema": { "type": "string", "maxLength": 512 },
    "outputSchema": { "type": "object", "properties": { "label": { "type": "string" }, "score": { "type": "number" } } }
  }],
  "id": 1
}
 
// Response
{
  "jsonrpc": "2.0",
  "result": {
    "modelId": "0xdef456...",
    "txHash": "0x789abc..."
  },
  "id": 1
}

citrate_getModel

Returns metadata for a registered model by its ID.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getModel", "params": ["0xdef456..."], "id": 1 }
 
// Response
{
  "jsonrpc": "2.0",
  "result": {
    "modelId": "0xdef456...",
    "name": "sentiment-v1",
    "format": "onnx",
    "owner": "0xOwnerAddress",
    "deployedAt": 1207,
    "inferenceCount": 4521
  },
  "id": 1
}

citrate_listModels

Returns a paginated list of all registered models.

// Request
{ "jsonrpc": "2.0", "method": "citrate_listModels", "params": [{ "offset": 0, "limit": 20 }], "id": 1 }

citrate_runInference

Executes an inference call against a deployed model. The input must conform to the model's declared input schema.

// Request
{
  "jsonrpc": "2.0",
  "method": "citrate_runInference",
  "params": [{
    "modelId": "0xdef456...",
    "input": "The Citrate protocol is fascinating.",
    "proofRequired": true
  }],
  "id": 1
}
 
// Response
{
  "jsonrpc": "2.0",
  "result": {
    "output": { "label": "positive", "score": 0.94 },
    "gasUsed": "0x7a120",
    "proof": "0xzkproof..."
  },
  "id": 1
}

citrate_getDagTips

Returns the current tip set of the GhostDAG, representing the most recent unconfirmed blocks.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getDagTips", "params": [], "id": 1 }
 
// Response
{
  "jsonrpc": "2.0",
  "result": {
    "tips": ["0xblock1...", "0xblock2...", "0xblock3..."],
    "tipCount": 3
  },
  "id": 1
}

citrate_getBlueSet

Returns the blue set (honest majority blocks) for a given block hash within the GhostDAG.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getBlueSet", "params": ["0xblock1..."], "id": 1 }

citrate_getDagStats

Returns statistics about the current GhostDAG state including depth, width, and confirmation metrics.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getDagStats", "params": [], "id": 1 }
 
// Response
{
  "jsonrpc": "2.0",
  "result": {
    "depth": 14523,
    "width": 3,
    "blueScore": 14201,
    "avgConfirmationTime": 1.2,
    "tipsCount": 3
  },
  "id": 1
}

citrate_getProof

Generates a zero-knowledge proof for a given inference result.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getProof", "params": ["0xinferenceId..."], "id": 1 }

citrate_verifyProof

Verifies a zero-knowledge inference proof on-chain.

// Request
{
  "jsonrpc": "2.0",
  "method": "citrate_verifyProof",
  "params": [{
    "proof": "0xzkproof...",
    "publicInputs": ["0xmodelId...", "0xinputHash..."]
  }],
  "id": 1
}
 
// Response
{ "jsonrpc": "2.0", "result": { "valid": true, "gasUsed": "0x30d40" }, "id": 1 }

citrate_requestInference

Submits an async inference request. Returns a request ID for polling.

// Request
{
  "jsonrpc": "2.0",
  "method": "citrate_requestInference",
  "params": [{
    "modelId": "0xdef456...",
    "input": "Analyze this text.",
    "proofRequired": false
  }],
  "id": 1
}
 
// Response
{ "jsonrpc": "2.0", "result": { "requestId": "0xreq789..." }, "id": 1 }

citrate_getInferenceResult

Polls for the result of an async inference request.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getInferenceResult", "params": ["0xreq789..."], "id": 1 }

citrate_getAIStatus

Returns the AI subsystem status including active models, pending inferences, and resource utilization.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getAIStatus", "params": [], "id": 1 }

citrate_createTrainingJob

Creates a training or fine-tuning job for a registered model.

// Request
{
  "jsonrpc": "2.0",
  "method": "citrate_createTrainingJob",
  "params": [{
    "modelId": "0xdef456...",
    "datasetUri": "ipfs://Qm...",
    "config": { "epochs": 3, "learningRate": 0.0001 }
  }],
  "id": 1
}

citrate_getTrainingJob

Returns the status and progress of a training job.

// Request
{ "jsonrpc": "2.0", "method": "citrate_getTrainingJob", "params": ["0xjob123..."], "id": 1 }

citrate_updateModel

Updates metadata for a registered model (owner only).

// Request
{
  "jsonrpc": "2.0",
  "method": "citrate_updateModel",
  "params": [{
    "modelId": "0xdef456...",
    "storageUri": "ipfs://QmNewHash..."
  }],
  "id": 1
}

citrate_pinArtifact / citrate_getArtifactStatus

Pin model artifacts to content-addressed storage and check their availability.

// Request
{ "jsonrpc": "2.0", "method": "citrate_pinArtifact", "params": [{ "uri": "ipfs://Qm...", "type": "model" }], "id": 1 }
 
// Check status
{ "jsonrpc": "2.0", "method": "citrate_getArtifactStatus", "params": ["ipfs://Qm..."], "id": 1 }

citrate_listModelArtifacts / citrate_listProofArtifacts

List artifacts associated with a model or proof store.

// Request
{ "jsonrpc": "2.0", "method": "citrate_listModelArtifacts", "params": ["0xdef456..."], "id": 1 }
{ "jsonrpc": "2.0", "method": "citrate_listProofArtifacts", "params": [{ "modelId": "0xdef456...", "limit": 10 }], "id": 1 }

citrate_getTextEmbedding / citrate_semanticSearch

Generate text embeddings and perform semantic search across registered models.

// Embedding
{ "jsonrpc": "2.0", "method": "citrate_getTextEmbedding", "params": [{ "text": "GhostDAG consensus" }], "id": 1 }
 
// Semantic search
{ "jsonrpc": "2.0", "method": "citrate_semanticSearch", "params": [{ "query": "consensus mechanism", "limit": 5 }], "id": 1 }

citrate_verifyContract / citrate_getVerification / citrate_listVerifications

Contract verification endpoints for source code verification against deployed bytecode.

// Submit verification
{
  "jsonrpc": "2.0",
  "method": "citrate_verifyContract",
  "params": [{
    "address": "0xContractAddress",
    "sourceCode": "// SPDX-License-Identifier...",
    "compilerVersion": "0.8.24"
  }],
  "id": 1
}
 
// Check verification
{ "jsonrpc": "2.0", "method": "citrate_getVerification", "params": ["0xContractAddress"], "id": 1 }
 
// List verifications (with optional filters)
{ "jsonrpc": "2.0", "method": "citrate_listVerifications", "params": [{ "status": "verified", "limit": 20 }], "id": 1 }
{ "jsonrpc": "2.0", "method": "citrate_listVerificationsByStatus", "params": ["verified"], "id": 1 }
{ "jsonrpc": "2.0", "method": "citrate_listVerificationsByAddressPrefix", "params": ["0xAB"], "id": 1 }

citrate_pruneVerifications

Remove expired or invalid verification records (admin only).

{ "jsonrpc": "2.0", "method": "citrate_pruneVerifications", "params": [{ "olderThanBlocks": 100000 }], "id": 1 }

Rate Limits

The following per-connection rate limits apply by default. Node operators can adjust these in their configuration.

Method	Limit
`eth_sendRawTransaction`	10 req/sec
`eth_call`	100 req/sec
`citrate_runInference`	5 req/sec
`citrate_deployModel`	1 req/sec
All other methods	200 req/sec

When a rate limit is exceeded, the server returns a JSON-RPC error with code -32005 and a Retry-After header indicating how many seconds to wait before retrying.

Error Codes

Code	Message	Meaning
-32700	Parse error	Invalid JSON
-32600	Invalid Request	Malformed JSON-RPC request
-32601	Method not found	The method does not exist
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Internal server error
-32005	Rate limit exceeded	Too many requests
-32010	Model not found	The specified model ID does not exist
-32011	Inference failed	Model inference execution failed
-32012	Proof generation failed	ZK proof could not be generated