Allocation Storage SDK Methods

In this section, we will learn about all the available Allocation Storage methods provided by the SDK.

Prerequisites

1. Initialize the SDK before using wallet methods. See the Quick Start Guide for details.
2. All methods require a wallet. Refer to createWallet for more information.
3. All methods require a domain parameter, which is the network domain where your wallet and providers such as blobbers, sharders, miners, and validators are deployed. GoSDK will send requests to this domain.

Allocation Storage Methods

The allocation storage methods allow you to create, update, and manage allocations.

createAllocation

Creates an allocation with the specified allocation terms and preferred blobber IDs.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active wallet details
dataShards	number	Number of data shards. Data uploaded to the allocation will be split and distributed across these shards.
parityShards	number	Number of parity shards. Parity shards are used to replicate data shards for redundancy.
size	number	Size of the allocation in bytes
minReadPrice	number	Minimum read price
maxReadPrice	number	Maximum read price
minWritePrice	number	Minimum write price
maxWritePrice	number	Maximum write price
lock	number	Lock value to add to the allocation. Use getAllocationMinLock to calculate this value
blobberIds	string[]	List of blobber IDs of your preferred blobbers for the allocation	[]
blobberAuthTickets	string[]	List of blobber auth tickets in case of using restricted blobbers
setThirdPartyExtendable	boolean	Determines whether third-parties are allowed to update the allocation's size and expiration property. When true, third-parties (e.g., 0box) can modify the allocation.
isEnterprise	boolean	Whether it's an enterprise allocation
force	boolean	Determines whether the allocation creation should proceed even if the available blobbers are insufficient to meet the required data + parity conditions. Use with caution as it may reduce fault tolerance.	false

note

To determine minReadPrice, maxReadPrice, minWritePrice, and maxWritePrice, use the makeSCRestAPICall SDK method to call the /storage-config endpoint of the sharder smart contract.

warning

The force parameter should be used with caution. Setting it to true may result in allocations with lower redundancy and reliability.

Return Type

Promise<Transaction>

Example

import { createAllocation } from '@zerochain/sdk'

const allocation = await createAllocation({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  dataShards: 4,
  parityShards: 2,
  size: 2147483648, // 2 GB
  minReadPrice: 0,
  maxReadPrice: 100,
  minWritePrice: 0.001,
  maxWritePrice: 100,
  lock: minLock,
  blobberIds: ['blobber1', 'blobber2'],
  blobberAuthTickets: ['ticket1', 'ticket2'],
  setThirdPartyExtendable: true,
  isEnterprise: false,
  force: false
})

getAllocationMinLock

Retrieves the minimum lock value for the allocation creation. The 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.

Parameters

Name	Type	Description
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active wallet details
dataShards	number	Number of data shards
parityShards	number	Number of parity shards
size	number	Size of the allocation in bytes
maxWritePrice	number	Maximum write price

note

To determine maxWritePrice, use the makeSCRestAPICall SDK method to call the /storage-config endpoint of the sharder smart contract.

Return Type

minLock token amount in terms of SAS tokens

Promise<number>

Example

import { getAllocationMinLock } from '@zerochain/sdk'

const minLock = await getAllocationMinLock({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  dataShards: 4,
  parityShards: 2,
  size: 2147483648, // 2 GB
  maxWritePrice: 100
})

listAllocations

Lists all the allocations.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocations
wallet	ActiveWallet	Active wallet details

Return Type

Promise<Allocation[]>

Example

import { listAllocations } from '@zerochain/sdk'

const allocations = await listAllocations({
  domain: 'mainnet.zus.network',
  wallet: activeWallet
})

getAllocation

Gets allocation details using allocationId from cache. If not found in cache, it fetches from the blockchain and stores in cache.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active wallet details
allocationId	string	ID of the allocation to fetch

Return Type

Promise<Allocation>

Example

import { getAllocation } from '@zerochain/sdk'

const allocation = await getAllocation({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3'
})

reloadAllocation

Reloads allocation details using allocationId from the blockchain and updates the cache.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
allocationId	string	ID of the allocation to reload

Return Type

Promise<Allocation>

Example

import { reloadAllocation } from '@zerochain/sdk'

const allocation = await reloadAllocation({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3'
})

getAllocationWith

Retrieves the information of a free allocation or a shared allocation given the auth ticket.

• Free allocation: An allocation created for the user using the Vult app for the first time with no fees.
• Shared allocation: An allocation that has shared files. The user accessing these files needs to read the allocation information using an auth ticket.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
authTicket	string	Auth ticket, used by a non-owner to access shared files

Return Type

Promise<Allocation>

Example

import { getAllocationWith } from '@zerochain/sdk'

const allocation = await getAllocationWith({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  authTicket: sharedFilesAuthTicket
})

freezeAllocation

Freezes one of the client's allocations, given its ID. Freezing the allocation will forbid all operations on the files in the allocation. Allocation will be read-only

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
allocationId	string	Allocation ID to freeze

Return Type

Promise<string>

Example

import { freezeAllocation } from '@zerochain/sdk'

const transactionHash = await freezeAllocation({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3'
})

cancelAllocation

Cancels an allocation using allocationId.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active wallet to authorize the cancellation
allocationId	string	Allocation ID to cancel

Return Type

Promise<string>

Example

import { cancelAllocation } from '@zerochain/sdk'

const transactionHash = await cancelAllocation({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: allocId
})

updateAllocation

Updates the allocation settings.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
allocationId	string	Allocation ID to update
size	number	New size of the allocation in bytes
extend	boolean	Whether to extend the allocation's expiration date. Use the same extend value as when calling getUpdateAllocationMinLock
lock	number	Lock value to add to the allocation. Use getUpdateAllocationMinLock to calculate this value.
addBlobberId	string	Blobber ID to add to the allocation	""
addBlobberAuthTicket	string	Blobber auth ticket to add, in case of restricted blobbers	""
removeBlobberId	string	Blobber ID to remove from the allocation	""
ownerSigningPublicKey	string | undefined	Optional ECDSA Public key of the user who created that allocation. It’s used for signature verification. If not provided, GoSDK will generate one	""
setThirdPartyExtendable	boolean	If true, a non-owner client can extend the allocation (in terms of size). When set to true, third-parties / a non-owner client (e.g., 0box) can update / modify the allocation

Returns

Promise<string>  

Example

const transactionHash = await updateAllocation({  
  domain,  
  wallet,  
  allocationId: allocationId,  
  size: sizeOfChosenStoragePlan,  
  extend: true,  
  lock: zcnAmountOfStoragePlan,  
  addBlobberId: addBlobberId,  
  addBlobberAuthTicket: addBlobberAuthTicket,
  removeBlobberId: removeBlobberId,
  setThirdPartyExtendable: false,  
})  

updateAllocationWithRepair

Updates your allocation settings and repairs the allocation if any blobber was replaced or added to the allocation.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
allocationId	string	Allocation ID to update
size	number	New size of the allocation in bytes
extend	boolean	Extend flag, whether to extend the allocation's expiration date. Use the same extend value as when calling getUpdateAllocationMinLock	false
lock	number	Lock value to add to the allocation. Use getUpdateAllocationMinLock to calculate this value.
addBlobberId	string	Blobber ID to add to the allocation	""
addBlobberAuthTicket	string	Blobber auth ticket to add to the allocation, in case of restricted blobbers	""
removeBlobberId	string	Blobber ID to remove from the allocation	""
ownerSigningPublicKey	string	Optional ECDSA Public key of the user who created the allocation. Used for signature verification. If not provided, GoSDK will generate one.	""
updateAllocTicket	string	Optional update allocation ticket. Refer to getUpdateAllocTicket	""
callback	(totalBytes: number, completedBytes: number, fileName: string, blobURL: string, error: string) => void	Callback function invoked with repair progress updates

Return Type

Promise<string>

Callback Parameters

Name	Type	Description
totalBytes	number	Total bytes to repair
completedBytes	number	Bytes repaired so far
fileName	string	Name of the file being repaired
blobURL	string	URL of the blobber being used for repair
error	string	Error message, if any

Example

import { updateAllocationWithRepair } from '@zerochain/sdk'

const transactionHash = await updateAllocationWithRepair({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3',
  size: desiredSize,
  extend: shouldExtendExpiry,
  lock: minLock,
  addBlobberId: addBlobberId,
  addBlobberAuthTicket: addBlobberAuthTicket,
  removeBlobberId: removeBlobberId,
  updateAllocTicket: updateAllocTicket,
  callback: (totalBytes, completedBytes, fileName, blobURL, error) => {
    console.log(`Repair progress: ${completedBytes}/${totalBytes} bytes`);
    if (error) {
      console.error(`Error: ${error}`);
    }
  }
})

getUpdateAllocationMinLock

Retrieves the minimum lock value for the allocation after an update, as calculated by the network based on the update parameters. The 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.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
allocationId	string	Allocation ID to update
size	number	New size of the allocation in bytes
extend	boolean	Extend flag, whether to extend the allocation's expiration date
addBlobberId	string	Blobber ID to add to the allocation
removeBlobberId	string	Blobber ID to remove from the allocation

Return Type

minLock token amount in terms of SAS tokens

Promise<number>

Example

import { getUpdateAllocationMinLock } from '@zerochain/sdk'

const minLock = await getUpdateAllocationMinLock({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3',
  size: 2147483648, // 2 GB
  extend: shouldExtendExpiry,
  addBlobberId: 'blobber1',
  removeBlobberId: 'blobber2'
})

updateForbidAllocation

Updates the permissions of an allocation.

Parameters

Name	Type	Description	Default value
wallet	ActiveWallet	Active Wallet details
domain	NetworkDomain	Network domain for the allocation
allocationId	string	Allocation ID to update
forbidUpload	boolean	If true, uploading files to the allocation is forbidden
forbidDelete	boolean	If true, deleting files from the allocation is forbidden
forbidUpdate	boolean	If true, updating files in the allocation is forbidden
forbidMove	boolean	If true, moving files in the allocation is forbidden
forbidCopy	boolean	If true, copying files in the allocation is forbidden
forbidRename	boolean	If true, renaming files in the allocation is forbidden

Return Type

Promise<string>

Example

import { updateForbidAllocation } from '@zerochain/sdk'

const transactionHash = await updateForbidAllocation({
  wallet: activeWallet,
  domain: 'mainnet.zus.network',
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3',
  forbidUpload: true,
  forbidDelete: false,
  forbidUpdate: false,
  forbidMove: true,
  forbidCopy: false,
  forbidRename: true
})

getUpdateAllocTicket

Generates and signs an "Update Allocation ticket", which authorizes the "add blobber" or "replace blobber" operation from other wallets.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
allocationId	string	Allocation ID to update
userId	string	UserID is the wallet ID which will be allowed to update your allocation
operationType	replace_blobber | add_blobber	Type of operation
roundExpiry	number	Round expiry is the round after which the auth ticket will no longer be valid.

Return Type

Promise<string>

Example

import { getUpdateAllocTicket } from '@zerochain/sdk'

const authTicket = await getUpdateAllocTicket({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3',
  userId: actorWalletId,
  operationType: 'add_blobber',
  roundExpiry: 1000
})

checkAllocStatus

Checks the health status of the allocation.

Parameters

Name	Type	Description	Default value
wallet	ActiveWallet	Active Wallet details
domain	NetworkDomain	Network domain for the allocation
allocationId	string	ID of the allocation to check the health status for.

Return Type

Promise<AllocStatus>

AllocStatus Type

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
}

Example

import { checkAllocStatus } from '@zerochain/sdk'

const allocStatus = await checkAllocStatus({
  wallet: activeWallet,
  domain: 'mainnet.zus.network',
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3'
})

console.log(allocStatus.status); // 'ok', 'repair', or 'broken'

skipStatusCheck

Skips the health status check of the allocation.

Parameters

Name	Type	Description	Default value
wallet	ActiveWallet	Active Wallet details
domain	NetworkDomain	Network domain for the allocation
allocationId	string	Allocation ID to skip status check for
checkStatus	boolean	Flag to enable or disable status check

Example

import { skipStatusCheck } from '@zerochain/sdk'

await skipStatusCheck({
  wallet: activeWallet,
  domain: 'mainnet.zus.network',
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3',
  checkStatus: false // Disable status check
})

repairAllocation

Repairs the allocation by re-uploading missing blocks to its blobbers. Allocation repair is a process to ensure the integrity and availability of files in the allocation.

Parameters

Name	Type	Description	Default value
wallet	ActiveWallet	Active Wallet details
domain	NetworkDomain	Network domain for the allocation
allocationId	string	Allocation ID to repair
callback	(totalBytes: number, completedBytes: number, fileName: string, blobURL: string, error: string) => void	Callback function invoked with repair progress updates

Callback Parameters

Name	Type	Description
totalBytes	number	Total bytes to repair
completedBytes	number	Bytes repaired so far
fileName	string	Name of the file being repaired
blobURL	string	URL of the blobber being used for repair
error	string	Error message, if any

Example

import { repairAllocation } from '@zerochain/sdk'

await repairAllocation({
  wallet: activeWallet,
  domain: 'mainnet.zus.network',
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3',
  callback: (totalBytes, completedBytes, fileName, blobURL, error) => {
    console.log(`Repair progress: ${completedBytes}/${totalBytes} bytes`);
    if (error) {
      console.error(`Error: ${error}`);
    }
  }
})

repairSize

Retrieves the repair size for a specific path in an allocation. The repair size is the size of the data that needs to be repaired in the blobbers of the allocation.

Parameters

Name	Type	Description	Default value
domain	NetworkDomain	Network domain for the allocation
wallet	ActiveWallet	Active Wallet details
allocationId	string	Allocation ID to check
remotePath	string	Path in the allocation to check for repair size

Return Type

Promise<{ upload_size: number; download_size: number }>

Example

import { repairSize } from '@zerochain/sdk'

const repairSizes = await repairSize({
  domain: 'mainnet.zus.network',
  wallet: activeWallet,
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3',
  remotePath: '/my-folder'
})

console.log(`Upload size: ${repairSizes.upload_size}, Download size: ${repairSizes.download_size}`);

createWorkers

Used to manually create local upload workers for an allocation. These workers are used to handle operations for the allocation. Terminate workers if the allocation is no longer needed using terminateWorkers.

info

1. There is no need to manually call createWorkers as it is automatically invoked when an upload begins.
2. To free up resources, make sure to call terminateWorkers once the allocation is no longer required.

Parameters

Name	Type	Description	Default value
wallet	ActiveWallet	Active Wallet details
domain	NetworkDomain	Network domain for the allocation
allocationId	string	Allocation ID to create workers for

Example

import { createWorkers } from '@zerochain/sdk'

await createWorkers({
  wallet: activeWallet,
  domain: 'mainnet.zus.network',
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3'
})

terminateWorkers

Removes local upload workers for a particular allocation.

note

Use this method to free up resources when switching between allocations, especially when uploads for the previously active allocation have completed or are no longer in progress.

Parameters

Name	Type	Description	Default value
wallet	ActiveWallet	Active Wallet details
domain	NetworkDomain	Network domain for the allocation
allocationId	string	Allocation ID to terminate workers for

Example

import { terminateWorkers } from '@zerochain/sdk'

await terminateWorkers({
  wallet: activeWallet,
  domain: 'mainnet.zus.network',
  allocationId: '8695f8af52cdfc1e66d879407a5278703579d31de7ce0e2cf1707fdec9cc14c3'
})