Skip to main content

SDK IPFS Beacon

This guide covers the SDK's IPFS beacon features: forcing IPFS as a source, selecting specific values from the beacon array, traversing historical blocks, and using custom beacon paths.

Force IPFS as the source​

By default the SDK chooses the source automatically (API if credentials are present, otherwise IPFS). To explicitly request the IPFS beacon:

const result = await sdk.ctrng.random({ src: "ipfs" });

Select a specific array index​

The IPFS beacon publishes an array of cTRNG values (currently 3, but this may grow). Use the index parameter to pick a specific value:

// First value (index 0)
const first = await sdk.ctrng.random({ src: "ipfs", index: 0 });

// Second value (index 1)
const second = await sdk.ctrng.random({ src: "ipfs", index: 1 });

// Third value (index 2)
const third = await sdk.ctrng.random({ src: "ipfs", index: 2 });

The index is 0-based. If the index exceeds the array length, it is automatically adjusted using a modulo operation (e.g., index 5 with 3 values resolves to index 2).

Traverse historical blocks​

Each IPFS beacon block links to the previous one via its previous field, forming a chain. Use the block parameter to traverse back through the chain:

// Get a value from block 10012
const historical = await sdk.ctrng.random({
  src: "ipfs",
  block: 10012,
  index: 1,
});

The block parameter accepts:

  • "INF" (default) -- Fetch from the latest block.
  • A number -- Traverse the previous chain back to that block's sequence number.

If the requested block number is greater than the current block, the SDK throws an error.

// Explicitly request the latest block
const latest = await sdk.ctrng.random({
  src: "ipfs",
  block: "INF",
  index: 0,
});

Use a custom beacon path​

If you operate your own IPFS beacon or want to point to a different one:

const result = await sdk.ctrng.random({
  src: "ipfs",
  beaconPath: "/ipns/your-custom-beacon-cid",
});

How IPFS integrity works​

When fetching from IPFS, the SDK reads from both the IPFS gateway and the IPFS API node, then compares the results to verify data integrity. This dual-fetch approach detects tampering or inconsistency.

Default IPFS configuration​

SettingDefault
Gatewayhttps://ipfs.io
APIhttps://ipfs.io
Beacon path/ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f

These defaults can be overridden through the SDK configuration. See SDK Advanced Configuration for details.

Next steps​