@zerochain/sdk/dist/sdk/allocation.d.ts

The Züs JS SDK is a JavaScript client library that provides a convenient interface for interacting with the Züs Network. It allows developers to perform various operations such as creating and managing allocations, uploading and downloading files, executi

import { type StakePoolInfo, type ActiveWallet, type NetworkDomain, type ProviderType, type Transaction } from '@/types/wallet';
import type { Allocation } from '@/types/allocation';
/**
 * Creates an allocation with the specified allocation terms and preferred blobber IDs.
 *
 * To determine `minReadPrice`, `maxReadPrice`, `minWritePrice`, and `maxWritePrice`, use the `makeSCRestAPICall` SDK method to call the `/storage-config` endpoint of the sharder smart contract.
 */
export declare const createAllocation: ({ wallet, domain, dataShards, parityShards, size, minReadPrice, maxReadPrice, minWritePrice, maxWritePrice, lock, blobberIds, blobberAuthTickets, setThirdPartyExtendable, isEnterprise, force, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Number of data shards. Data uploaded to the allocation will be split and distributed across these shards. */
    dataShards: number;
    /** Number of parity shards. Parity shards are used to replicate datashards for redundancy. */
    parityShards: number;
    /** Size of the allocation in bytes */
    size: number;
    /** Minimum read price */
    minReadPrice: number;
    /** Maximum read price */
    maxReadPrice: number;
    /** Minimum write price */
    minWritePrice: number;
    /** Maximum write price */
    maxWritePrice: number;
    /** Lock value to add to the allocation */
    lock: number;
    /** List of blobber IDs of your preferred blobbers for the allocation */
    blobberIds?: string[];
    /** List of blobber auth tickets in case of using restricted blobbers */
    blobberAuthTickets: string[];
    /**
     * setThirdPartyExtendable is a flag that determines whether third-parties are allowed to update the allocation's size and expiration property.
     *
     * When set to `true`, third-parties / a non-owner client (e.g., 0box) can update or modify the allocation
     */
    setThirdPartyExtendable: boolean;
    /** Whether it's an enterprise allocation */
    isEnterprise: boolean;
    /**
     * The `force` parameter determines whether the allocation creation should proceed even if the available blobbers are insufficient to meet the required data + parity conditions.
     *
     * By default, when `force` is `false`, the API will return a "Not enough blobbers" error if the number of available blobbers is less than the required data + parity. This ensures that the allocation meets the necessary redundancy and reliability conditions.
     *
     * When `force` is set to `true`, the API will bypass this check and proceed with the allocation creation using the available blobbers, even if they are fewer than the required data + parity shards. This can be useful in scenarios where you want to proceed with the allocation despite the reduced redundancy.
     *
     * Use this parameter with caution, as it may result in allocations with lower fault tolerance and reliability.
     */
    force: boolean;
}) => Promise<Transaction>;
/**
 * Retrieves list of blobber IDs of blobber which match your allocation terms
 *
 * To determine `minReadPrice`, `maxReadPrice`, `minWritePrice`, and `maxWritePrice`, use the `makeSCRestAPICall` SDK method to call the `/storage-config` endpoint of the sharder smart contract.
 */
export declare const getAllocationBlobbers: ({ wallet, domain, preferredBlobberURLs, dataShards, parityShards, size, minReadPrice, maxReadPrice, minWritePrice, maxWritePrice, restrictedLevel, force, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** List of preferred blobber URLs */
    preferredBlobberURLs?: string[];
    /** Number of data shards */
    dataShards: number;
    /** Number of parity shards */
    parityShards: number;
    /** Size of the allocation in bytes */
    size: number;
    /** Minimum read price */
    minReadPrice: number;
    /** Maximum read price */
    maxReadPrice: number;
    /** Minimum write price */
    minWritePrice: number;
    /** Maximum write price */
    maxWritePrice: number;
    /**
     * Specifies the type of blobbers to query.
     *
     * - `0`: Use all blobbers (both restricted and non-restricted).
     * - `1`: Use only restricted blobbers (require permission for allocation creation).
     * - `2`: Use only non-restricted blobbers (do not require permission for allocation creation).
     */
    restrictedLevel: number;
    /**
     * @deprecated For internal use only
     * @default false
     */
    force: boolean;
}) => Promise<string[]>;
/** List all the allocations */
export declare const listAllocations: ({ wallet, domain, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
}) => Promise<Allocation[]>;
/** getAllocation gets allocation details using `allocationId` from cache
 *  - if not found in cache, fetch from blockchain and store in cache */
export declare const getAllocation: ({ wallet, domain, allocationId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    allocationId: string;
}) => Promise<Allocation>;
/** reloadAllocation reload allocation details using `allocationId` from blockchain and updates cache */
export declare const reloadAllocation: ({ wallet, domain, allocationId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    allocationId: string;
}) => Promise<Allocation>;
/**
 * transferAllocation transfers the ownership of an allocation to a new owner
 * @deprecated
 */
export declare const transferAllocation: ({ wallet, domain, allocationId, newOwnerId, newOwnerPublicKey, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    allocationId: string;
    /** New owner ID */
    newOwnerId: string;
    /** New owner public key */
    newOwnerPublicKey: string;
}) => Promise<void>;
/**
 * freezeAllocation freezes one of the client's allocations, given its ID
 *
 * Freezing the allocation will forbid all the operations on the files in the allocation.
 *
 * @returns the hash of the transaction
 */
export declare const freezeAllocation: ({ wallet, domain, allocationId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Allocation ID to freeze */
    allocationId: string;
}) => Promise<string>;
/**
 * cancelAllocation cancels an allocation using `allocationId`
 *
 * @returns the hash of the transaction
 */
export declare const cancelAllocation: ({ wallet, domain, allocationId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Allocation ID to cancel */
    allocationId: string;
}) => Promise<string>;
/** updateAllocation updates the allocation settings */
export declare const updateAllocation: ({ wallet, domain, allocationId, size, extend, lock, addBlobberId, addBlobberAuthTicket, removeBlobberId, ownerSigningPublicKey, setThirdPartyExtendable, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Allocation ID to update */
    allocationId: string;
    /** New size of the allocation in bytes */
    size: number;
    /** Extend flag, whether to extend the allocation's expiration date */
    extend: boolean;
    /** Lock value to add to the allocation */
    lock: number;
    /** Blobber ID to add to the allocation */
    addBlobberId?: string;
    /** Blobber auth ticket to add to the allocation, in case of restricted blobbers */
    addBlobberAuthTicket?: string;
    /** Blobber ID to remove from the allocation */
    removeBlobberId?: string;
    /** Optional ECDSA Public key of the user who created that allocation. It’s used for signature verification. If not provided, GoSDK will generate one  */
    ownerSigningPublicKey?: string;
    /**
     * setThirdPartyExtendable is a flag that determines whether third-parties are allowed to update the allocation's size and expiration property.
     *
     * When set to `true`, third-parties / a non-owner client (e.g., 0box) can update or modify the allocation
     */
    setThirdPartyExtendable: boolean;
}) => Promise<string>;
/** Updates your allocation settings and repairs the allocation if any blobber was replaced or added to the allocation  */
export declare const updateAllocationWithRepair: ({ wallet, domain, allocationId, size, extend, lock, addBlobberId, addBlobberAuthTicket, removeBlobberId, ownerSigningPublicKey, updateAllocTicket, callback, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Allocation ID to update */
    allocationId: string;
    /** New size of the allocation in bytes */
    size: number;
    /**
     * Extend flag, whether to extend the allocation's expiration date
     * @default false
     */
    extend: boolean;
    /** Lock value to add to the allocation */
    lock: number;
    /** Blobber ID to add to the allocation */
    addBlobberId?: string;
    /** Blobber auth ticket to add to the allocation, in case of restricted blobbers */
    addBlobberAuthTicket?: string;
    /** Blobber ID to remove from the allocation */
    removeBlobberId?: string;
    /** Optional ECDSA Public key of the user who created that allocation. It’s used for signature verification. If not provided, GoSDK will generate one  */
    ownerSigningPublicKey?: string;
    /** Update allocation ticket */
    updateAllocTicket?: string;
    /** Callback function will be invoked with repair progress updates */
    callback?: (totalBytes: number, completedBytes: number, fileName: string, blobURL: string, error: string) => void;
}) => Promise<string>;
/**
 * getAllocationMinLock retrieves the minimum lock value for the allocation creation
 *
 * Lock value is the amount of tokens that the client needs to lock in the allocation's write pool to be able to pay for the write operations.
 *
 * To determine `maxWritePrice`, use the `makeSCRestAPICall` SDK method to call the `/storage-config` endpoint of the sharder smart contract.
 *
 * @returns the minimum lock value (in SAS)
 */
export declare const getAllocationMinLock: ({ domain, wallet, dataShards, parityShards, size, maxWritePrice, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Number of data shards */
    dataShards: number;
    /** Number of parity shards */
    parityShards: number;
    /** Size of the allocation in bytes */
    size: number;
    /** Maximum write price */
    maxWritePrice: number;
}) => Promise<number>;
/**
 * getUpdateAllocationMinLock retrieves the minimum lock value for the allocation after update, as calculated by the network based on the update parameters.
 *
 * Lock value is the amount of tokens that the client needs to lock in the allocation's write pool to be able to pay for the write operations.
 *
 * @returns the minimum lock value (in SAS)
 */
export declare const getUpdateAllocationMinLock: ({ domain, wallet, allocationId, size, extend, addBlobberId, removeBlobberId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Allocation ID to update */
    allocationId: string;
    /** New size of the allocation in bytes */
    size: number;
    /** Extend flag, whether to extend the allocation's expiration date */
    extend: boolean;
    /** Blobber ID to add to the allocation */
    addBlobberId?: string;
    /** Blobber ID to remove from the allocation */
    removeBlobberId?: string;
}) => Promise<number>;
/**
 * UpdateForbidAllocation updates the permissions of an allocation.
 *
 * @returns The transaction hash
 */
export declare const updateForbidAllocation: ({ wallet, domain, allocationId, forbidUpload, forbidDelete, forbidUpdate, forbidMove, forbidCopy, forbidRename, }: {
    wallet: ActiveWallet;
    domain: NetworkDomain;
    /** Allocation ID to update */
    allocationId: string;
    /** If true, uploading files to the allocation is forbidden */
    forbidUpload: boolean;
    /** If true, deleting files from the allocation is forbidden */
    forbidDelete: boolean;
    /** If true, updating files in the allocation is forbidden */
    forbidUpdate: boolean;
    /** If true, moving files in the allocation is forbidden */
    forbidMove: boolean;
    /** If true, copying files in the allocation is forbidden */
    forbidCopy: boolean;
    /** If true, renaming files in the allocation is forbidden */
    forbidRename: boolean;
}) => Promise<string>;
/**
 * getAllocationWith retrieves the information of a free or a shared allocation given the auth ticket.
 * - **Free allocation** is an allocation that is created to the user using Vult app for the first time with no fees.
 * - **Shared allocation** is an allocation that has some shared files. The user who needs to access those files first needs to read the information of this allocation using an auth ticket.
 */
export declare const getAllocationWith: ({ domain, wallet, authTicket, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    /** Auth ticket, used by a non-owner to access a shared allocation */
    authTicket: string;
}) => Promise<Allocation>;
/** createFreeAllocation creates a free allocation */
export declare const createFreeAllocation: ({ domain, wallet, freeStorageMarker, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    freeStorageMarker: string;
}) => Promise<string>;
/**
 * Generates and signs an "Update Allocation ticket", which authorizes the "add blobber" or "replace blobber" operation from other wallets. This ticket must be signed by the allocation owner.
 */
export declare const getUpdateAllocTicket: ({ domain, wallet, allocationId, userId, operationType, roundExpiry, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    allocationId: string;
    /** UserID is the wallet ID which will be allowed to update your allocation */
    userId: string;
    operationType: "replace_blobber" | "add_blobber";
    /** Round expiry is the round after which the auth ticket will no longer be valid. */
    roundExpiry: number;
}) => Promise<string>;
/**
 * CollectRewards collect all rewards which are available for delegate & provider pair. (txn: `storagesc.collect_reward`)
 *
 * @returns the hash of the transaction
 */
export declare const collectRewards: ({ domain, wallet, providerType, providerId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    providerType: ProviderType;
    providerId: string;
}) => Promise<string>;
/** getSkatePoolInfo is to get information about the stake pool for the allocation */
export declare const getStakePoolInfo: ({ domain, wallet, providerType, providerId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    providerType: ProviderType;
    providerId: string;
}) => Promise<StakePoolInfo>;
/**
 * Stake number of tokens for a given provider given its type and ID
 * @returns the hash of the transaction
 */
export declare const lockStakePool: ({ domain, wallet, providerType, tokens, fee, providerId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    providerType: ProviderType;
    /** Number of tokens to lock (in SAS) */
    tokens: number;
    /** Transaction fee (in SAS) */
    fee: number;
    providerId: string;
}) => Promise<string>;
/**
 * unlockStakePool unlocks the write pool
 * @returns the hash of the transaction
 */
export declare const unlockStakePool: ({ domain, wallet, providerType, fee, providerId, clientId, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    providerType: ProviderType;
    /** Transaction fee (in SAS) */
    fee: number;
    providerId: string;
    /** Wallet ID */
    clientId: string;
}) => Promise<string>;
/**
 * lockWritePool locks given number of tokes for given duration in write pool
 * @returns the hash of the transaction
 */
export declare const lockWritePool: ({ domain, wallet, allocationId, tokens, fee, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    allocationId: string;
    /** Number of tokens to lock (in SAS) */
    tokens: number;
    /** Transaction fee (in SAS) */
    fee: number;
}) => Promise<string>;
/**
 * Issues the repair process for an allocation, *starting from a specific path*.
 *
 * Repair synchronizes the user's data within the allocation across all blobbers and restores any missing data on blobbers where it is incomplete.
 *
 * @deprecated
 */
export declare const allocationRepair: ({ domain, wallet, allocationId, remotePath, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    allocationId: string;
    remotePath: string;
}) => Promise<void>;
/** Repairs the allocation.
 *
 * Allocation repair is a process to repair the allocation files on its blobbers by re-uploading the missing blocks. */
export declare const repairAllocation: ({ wallet, domain, allocationId, callback, }: {
    wallet: ActiveWallet;
    domain: NetworkDomain;
    allocationId: string;
    /** Callback function will be invoked with repair progress updates */
    callback?: (totalBytes: number, completedBytes: number, fileName: string, blobURL: string, error: string) => void;
}) => Promise<void>;
/**
 * repairSize retrieves the repair size for a specific path in an allocation
 *
 * Repair size is the size of the data that needs to be repaired in the allocation.
 */
export declare const repairSize: ({ domain, wallet, allocationId, remotePath, }: {
    domain: NetworkDomain;
    wallet: ActiveWallet;
    allocationId: string;
    remotePath: string;
}) => Promise<{
    upload_size: number;
    download_size: number;
}>;
type AllocStatus = {
    /**
     * The health `status` of the allocation has one of the following values:
     * - `ok`: The allocation is healthy and fully functional.
     * - `repair`: The allocation needs to be repaired. Repair using the `repairAllocation` method.
     * - `broken`: The allocation is irreparably broken. This occurs when critical data blocks are missing or when blobbers are offline, making recovery impossible.
     */
    status: 'ok' | 'repair' | 'broken';
    blobberStatus: {
        ID: string;
        Status: 'available' | 'unavailable';
    }[];
    error: string;
};
/** Check the health status of the allocation. */
export declare const checkAllocStatus: ({ wallet, domain, allocationId, }: {
    wallet: ActiveWallet;
    domain: NetworkDomain;
    allocationId: string;
}) => Promise<AllocStatus>;
/** Skip the health status check of the allocation. */
export declare const skipStatusCheck: ({ wallet, domain, allocationId, checkStatus, }: {
    wallet: ActiveWallet;
    domain: NetworkDomain;
    allocationId: string;
    /** Flag to enable or disable status check */
    checkStatus: boolean;
}) => Promise<void>;
/** Remove local workers for a particular allocation. This is useful when switching between allocations and we don't need workers for the old allocation. */
export declare const terminateWorkers: ({ wallet, domain, allocationId, }: {
    wallet: ActiveWallet;
    domain: NetworkDomain;
    allocationId: string;
}) => Promise<void>;
/** Create local workers for an allocation. Terminate workers if the allocation is no longer needed using `terminateWorkers`. */
export declare const createWorkers: ({ wallet, domain, allocationId, }: {
    wallet: ActiveWallet;
    domain: NetworkDomain;
    allocationId: string;
}) => Promise<void>;
export {};