The Codex SDK provides an API for interacting with the Codex decentralized storage network.
The SDK has a small bundle size and support tree shaking.
The SDK is currently under early development and the API can change at any time.
The easiest way is to use the sync API, but you will not benefit from tree shaking.
import { Codex } from "@codex-storage/sdk-js";
or
const { Codex } = require("@codex-storage/sdk-js");
To create a Codex instance, provide the REST API url to interact with the Codex client:
const codex = new Codex("http://localhost:3000");
Then you can access any module like this:
const marketplace = codex.marketplace;
import { Codex } from "@codex-storage/sdk-js/async";
or
const { Codex } = require("@codex-storage/sdk-js/async");
To create a Codex instance, provide the REST API url to interact with the Codex client:
const codex = new Codex("http://localhost:3000");
To use a module, you need to use the await syntax. If the module is not loaded yet, it will be imported first and then cached in memory.
const marketplace = await codex.marketplace;
The SDK provides a type called SafeValue
for error handling instead of throwing errors. It is inspired by Go's "error as value" concept.
If the value represents an error, error
is true and data
will contain the error.
If the value is not an error, error
is false and data
will contain the requested data.
The CodexError contains a message and 3 optionals properties:
code
: The (http) code error when it comes from a requesterrors
: A {ValidationError} array when it comes from an object validation processstack
: The error stack when the CodexError results from a error thrown
Example:
const slots = marketplace.activeSlots();
if (slots.error) {
// Do something to handle the error in slots.data
return;
}
// Access the slots within slots.data.
The following API assume that you have already a marketplace module loaded, example:
const codex = new Codex("http://localhost:3000");
const marketplace = await codex.marketplace();
Returns active slots.
- returns Promise<CodexSlot[]>
Example:
const slots = await marketplace.activeSlots();
Returns active slot with id {slotId} for the host.
- slotId (string, required)
- returns Promise<CodexSlot[]>
Example:
const slotId = "AB9........";
const slot = await marketplace.activeSlot(slotId);
Returns storage that is for sale.
- returns Promise<CodexAvailability>
Example:
const availabilities = await marketplace.availabilities();
Offers storage for sale.
- input (CodexCreateAvailabilityInput, required)
- returns Promise<CodexAvailabilityCreateResponse[]>
Example:
const response = await marketplace.createAvailability({
maxCollateral: 1,
totalSize: 3000,
minPrice: 100,
duration: 100,
});
Updates availability.
- input (CodexUpdateAvailabilityInput, required)
- returns Promise<"">
Example:
const response = await marketplace.updateAvailability({
id: "0x.....................",
maxCollateral: 1,
totalSize: 3000,
minPrice: 100,
duration: 100,
});
Return list of reservations for ongoing Storage Requests that the node hosts.
- availabilityId (string, required)
- returns Promise<CodexReservation[]>
Example:
const reservations = await marketplace.reservations("Ox...");
Creates a new Request for storage
- input (CodexCreateStorageRequestInput, required)
- returns Promise
Example:
const request = await marketplace.createStorageRequest({
duration: 3000,
reward: 100,
proofProbability: 1,
nodes: 1,
tolerance: 0,
collateral: 100,
expiry: 3000,
});
Returns list of purchase IDs
- returns Promise<string[]>
Example:
const ids = await marketplace.purchaseIds();
Returns purchase details
- purchaseId (string, required)
- returns Promise<CodexPurchase[]>
Example:
const purchaseId = "Ox........";
const purchase = await marketplace.purchaseDetail(purchaseId);
The following API assume that you have already a data module loaded, example:
const codex = new Codex("http://localhost:3000");
const data = await codex.data;
Returns the manifest stored locally in node.
- returns Promise<CodexDataResponse[]>
Example:
const cids = await data.cids();
Returns a summary of the storage space allocation of the node
- returns Promise<CodexNodeSpace[]>
Example:
const space = await data.space();
Upload a file in a streaming manner
- file (File, require)
- onProgress (onProgress: (loaded: number, total: number) => void, optional)
- returns UploadResponse
Example:
// Get file from previous event
const [file] = e.target.files
const upload = data.upload(file, (loaded: number, total: number) => {
// Use loaded and total so update a progress bar for example
});
await upload.result();
The following API assume that you have already a node module loaded, example:
const codex = new Codex("http://localhost:3000");
const data = await codex.debug;
Set log level at run time.
- level (CodexLogLevel, required)
- returns Promise<"">
Example:
await debug.setLogLevel("DEBUG");
Gets node information
- returns Promise<CodexDebugInfo>
Example:
const info = await debug.info();
The following API assume that you have already a node module loaded, example:
const codex = new Codex("http://localhost:3000");
const node = await codex.node;
Get Node's SPR
- returns Promise<CodexSpr>
Example:
const spr = await node.spr();