All pallets

Preimage docs

Look up any call, event, or storage item with code examples. Runtime v472 · Block #9,197,056

Developer documentation for the Preimage pallet of the Subtensor blockchain, part of the Bittensor decentralized AI network. This page is designed for developers integrating with the chain: look up any call, event, or storage item, copy code examples in TypeScript, Python, or Rust, and filter by your role. For in-depth explanations, version history, and relationships between items, see the Reference section.

Preimage

Register a preimage on-chain.

Index: 14 19 items

Calls 5

note_preimage

call details

Stores a preimage on-chain.

Parameters

NameTypeFormatDescription
bytesVec<u8>Array of Integer (0-255)bytes (Vec<u8>)
Emits: Noted
Modifies: PreimageFor/ StatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Build note_preimage call (typed, named args)
const bytes = Binary.fromOpaque(new Uint8Array(0));

const tx = api.tx.Preimage.note_preimage({
  bytes,
});

unnote_preimage

call details

Removes an unrequested preimage.

Parameters

NameTypeFormatDescription
hashH256256-bit Hashhash: Cryptographic hash (32 bytes)
Emits: Noted/ Cleared
Modifies: PreimageFor/ StatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Build unnote_preimage call (typed, named args)
const hash = "0x0000000000000000000000000000000000000000000000000000000000000000";

const tx = api.tx.Preimage.unnote_preimage({
  hash,
});

request_preimage

call details

Requests a preimage for use.

Parameters

NameTypeFormatDescription
hashH256256-bit Hashhash: Cryptographic hash (32 bytes)
Emits: Requested
Modifies: StatusFor/ RequestStatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Build request_preimage call (typed, named args)
const hash = "0x0000000000000000000000000000000000000000000000000000000000000000";

const tx = api.tx.Preimage.request_preimage({
  hash,
});

unrequest_preimage

call details

Removes request for a preimage.

Parameters

NameTypeFormatDescription
hashH256256-bit Hashhash: Cryptographic hash (32 bytes)
Emits: Requested/ Cleared
Modifies: StatusFor/ RequestStatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Build unrequest_preimage call (typed, named args)
const hash = "0x0000000000000000000000000000000000000000000000000000000000000000";

const tx = api.tx.Preimage.unrequest_preimage({
  hash,
});

ensure_updated

call details

Ensures preimage status is current.

Parameters

NameTypeFormatDescription
hashesVec<H256>Array of 256-bit Hashhashes: list of Cryptographic hash (32 bytes)
Modifies: PreimageFor/ StatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Build ensure_updated call (typed, named args)
const hashes = [] as [];

const tx = api.tx.Preimage.ensure_updated({
  hashes,
});

Events 3

Noted

event details

A preimage has been stored on-chain.

When it fires

  • Data provided
  • Hash unique

Fields

NameTypeFormatDescription
hashH256256-bit Hashhash: Cryptographic hash (32 bytes)
Emitted by: note_preimage/ unnote_preimage
Modifies: PreimageFor/ StatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Subscribe to Noted events
client.finalizedBlock$.subscribe(async (block) => {
  const events = await api.event.Preimage.Noted.get(block.hash);
  for (const evt of events) {
    console.log("Noted:", evt.payload);
  }
});

Requested

event details

A preimage has been requested.

When it fires

  • Hash provided

Fields

NameTypeFormatDescription
hashH256256-bit Hashhash: Cryptographic hash (32 bytes)
Emitted by: request_preimage/ unrequest_preimage
Modifies: RequestStatusFor/ StatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Subscribe to Requested events
client.finalizedBlock$.subscribe(async (block) => {
  const events = await api.event.Preimage.Requested.get(block.hash);
  for (const evt of events) {
    console.log("Requested:", evt.payload);
  }
});

Cleared

event details

A preimage has been cleared.

When it fires

  • Preimage exists
  • Not requested

Fields

NameTypeFormatDescription
hashH256256-bit Hashhash: Cryptographic hash (32 bytes)
Emitted by: unnote_preimage/ unrequest_preimage
Modifies: PreimageFor/ RequestStatusFor/ StatusFor
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Subscribe to Cleared events
client.finalizedBlock$.subscribe(async (block) => {
  const events = await api.event.Preimage.Cleared.get(block.hash);
  for (const evt of events) {
    console.log("Cleared:", evt.payload);
  }
});

Storage 3

PreimageFor

storage details

Actual preimage data stored by (hash, length).

Modifier: Optional Keys: 2 Returns: BoundedVec

Keys

NameTypeFormatDescription
key1H256256-bit Hash—
key2u32Integer—
Modified by: ensure_updated/ note_preimage/ unnote_preimage
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Query PreimageFor storage
const key1 = "0x0000000000000000000000000000000000000000000000000000000000000000";
const key2 = 0;

const result = await api.query.Preimage.PreimageFor.getValue(key1, key2);
console.log("PreimageFor:", result);

RequestStatusFor

storage details

Request status for preimages.

Modifier: Optional Keys: 1 Returns: RequestStatus

Keys

NameTypeFormatDescription
key1H256256-bit Hash—
Modified by: request_preimage/ unrequest_preimage
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Query RequestStatusFor storage
const key1 = "0x0000000000000000000000000000000000000000000000000000000000000000";

const result = await api.query.Preimage.RequestStatusFor.getValue(key1);
console.log("RequestStatusFor:", result);

StatusFor

storage details

Status of a preimage by hash (deprecated).

Modifier: Optional Keys: 1 Returns: OldRequestStatus

Keys

NameTypeFormatDescription
key1H256256-bit Hash—
Modified by: ensure_updated/ note_preimage/ request_preimage/ unnote_preimage/ unrequest_preimage
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443

const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);

// Query StatusFor storage
const key1 = "0x0000000000000000000000000000000000000000000000000000000000000000";

const result = await api.query.Preimage.StatusFor.getValue(key1);
console.log("StatusFor:", result);

Errors 8

TooBig

error details #0

The preimage data exceeds the maximum allowed size. Preimages store encoded call data for deferred execution (e.g., governance proposals) and have a size limit to prevent state bloat.

Common Causes

  • Proposal call data is too large when SCALE-encoded
  • Trying to store a batch call with too many sub-calls
  • Embedded data (like code upgrades) exceeds the limit

How to Fix

Reduce the size of the call data (e.g., fewer batch calls),Split large operations into multiple smaller proposals,Check the MaxSize constant for the current limit

AlreadyNoted

error details #1

A preimage with this hash has already been stored. Preimages are identified by the Blake2 hash of their content, so identical call data will always produce the same hash.

Common Causes

  • Submitting the same preimage (call data) that was already stored
  • Another account already noted this exact preimage
  • Accidentally calling note_preimage twice

How to Fix

Query Preimage.StatusFor with the hash to confirm it exists,Use the existing preimage — no need to store it again,If you need a different preimage, modify the call parameters

NotAuthorized

error details #2

You are not authorized to remove (unnote) this preimage. Only the account that originally stored the preimage and paid the deposit can remove it.

Common Causes

  • Trying to unnote a preimage that was stored by a different account
  • Using the wrong account to sign the unnote transaction

How to Fix

Query Preimage.StatusFor to find the depositor account,Sign the unnote transaction with the original depositor account,If the preimage is no longer needed and you are not the depositor, the depositor must remove it

NotNoted

error details #3

No preimage exists with this hash. The preimage was either never stored, already removed, or the hash is incorrect.

Common Causes

  • Wrong preimage hash
  • Preimage was already removed (unnoted) by its depositor
  • Preimage was never stored in the first place

How to Fix

Query Preimage.StatusFor to check if the hash exists,Verify the hash matches the expected call data,Store the preimage first using note_preimage if it does not exist

Requested

error details #4

This preimage is currently requested by the governance system (e.g., a pending proposal references it). It cannot be removed while something depends on it.

Common Causes

  • Trying to unnote a preimage that is referenced by an active governance proposal
  • A scheduled call depends on this preimage data
  • The preimage has active request references

How to Fix

Wait for the governance proposal or scheduled call to execute or be cancelled,Query Preimage.RequestStatusFor to check who is requesting it,The preimage will become removable after all requesters release it

NotRequested

error details #5

The preimage you are trying to unrequest is not currently in a requested state. It was either never requested or already unrequested.

Common Causes

  • The request reference was already released
  • The preimage was never requested by this mechanism
  • The governance action that requested it was already completed

How to Fix

Query Preimage.RequestStatusFor to check the request status,No action needed if the request was already released

TooMany

error details #6

The preimage has too many outstanding request references. There is a maximum number of concurrent requesters allowed per preimage.

Common Causes

  • Multiple governance mechanisms all requesting the same preimage simultaneously
  • Request reference count overflow

How to Fix

Wait for some requesters to release their references,Query Preimage.RequestStatusFor to check the current reference count

TooFew

error details #7

Cannot decrease the request reference count below zero. This typically indicates an internal bookkeeping issue where unrequest was called more times than request.

Common Causes

  • Unrequest called without a matching request
  • Internal reference count underflow

How to Fix

Query Preimage.RequestStatusFor to check the current reference count,This is likely a bug — report it if encountered in normal operation