logos-storage-js/README.md

Codex SDK

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.

Import

import { Codex } from "@codex/sdk-js";

or

const { Codex } = require("@codex/sdk-js");

How to use

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();

Error handling

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 request
• errors: A {ValidationError} array when it comes from an object validation process
• stack: 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.

Marketplace

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();

activeSlots()

Returns active slots.

• returns Promise<CodexSlot[]>

Example:

const slots = await marketplace.activeSlots();

activeSlot(slotId)

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);

availabilities

Returns storage that is for sale.

• returns Promise<CodexAvailability>

Example:

const availabilities = await marketplace.availabilities();

createAvailability

Offers storage for sale.

• input (CodexCreateAvailabilityInput, required)
• returns Promise<CodexAvailabilityCreateResponse[]>

Example:

const response = await marketplace.createAvailability({
  maxCollateral: 1,
  totalSize: 3000,
  minPrice: 100,
  duration: 100,
});

reservations

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...");

createStorageRequest

Creates a new Request for storage

• input (CodexCreateStorageRequestInput, required)
• returns Promise<CodexCreateStorageRequestResponse[]>

Example:

const request = await marketplace.createStorageRequest({
  duration: 3000,
  reward: 100,
  proofProbability: 1,
  nodes: 1,
  tolerance: 0,
  collateral: 100,
  expiry: 3000,
});

purchaseIds

Returns list of purchase IDs

• returns Promise<string[]>

Example:

const ids = await marketplace.purchaseIds();

purchaseDetail

Returns purchase details

• purchaseId (string, required)
• returns Promise<CodexPurchase[]>

Example:

const purchaseId = "Ox........";
const purchase = await marketplace.purchaseDetail(purchaseId);