# Storage S.C.

{% hint style="info" %}
This page is under progressive development.
{% endhint %}

### Allocation-related functions <a href="#allocation-related-functions" id="allocation-related-functions"></a>

#### `new_allocation_request`

Create a new allocation and lock tokens in the client's write pool, given the following inputs:

```go
type newAllocationRequest struct {
	Name                 string     `json:"name"`
	DataShards           int        `json:"data_shards"`
	ParityShards         int        `json:"parity_shards"`
	Size                 int64      `json:"size"`
	Owner                string     `json:"owner_id"`
	OwnerPublicKey       string     `json:"owner_public_key"`
	Blobbers             []string   `json:"blobbers"`
	BlobberAuthTickets   []string   `json:"blobber_auth_tickets"`
	ReadPriceRange       PriceRange `json:"read_price_range"`
	WritePriceRange      PriceRange `json:"write_price_range"`
	ThirdPartyExtendable bool       `json:"third_party_extendable"`
	FileOptionsChanged   bool       `json:"file_options_changed"`
	FileOptions          uint16     `json:"file_options"`
}
```

| Field                    | Description                                                                                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                     | (not used) the name of the allocation                                                                                                                 |
| data\_shards             | Number of data shards.                                                                                                                                |
| parity\_shards           | Number of prity shards used for error correction.                                                                                                     |
| size                     | Size of the allocation.                                                                                                                               |
| owner                    | ClientID of the owner of the alloaction.                                                                                                              |
| owner\_public\_key       | Public Key of the owner of the allocation.                                                                                                            |
| blobbers                 | List of blobber IDs to show for the blobbers.                                                                                                         |
| blobber\_auth\_tickets   | List of auth tickets corresponding to the list of blobber ids to host the allocation.                                                                 |
| read\_price\_range       | Range of read price offer for the blobbers chosen for the allocation (Reads in Züs are free!).                                                        |
| write\_price\_range      | Range of write price offer for the blobbers chosen for the allocation.                                                                                |
| third\_party\_extendable | Whether the allocation can be extendable by third party or not, meaning its size can be increased by a client other than the owner of the allocation. |
| file\_options\_changed   | Whether file option flags are changed.                                                                                                                |
| file\_options            | File option flags mask which control permissions of the files that belong to the allocation.                                                          |

#### `update_allocation_request`

Updates the parameters of an existing allocation given the following parameters:​

```go
type updateAllocationRequest struct {
	ID                      string `json:"id"`               // allocation id
	Name                    string `json:"name"`             // allocation name
	OwnerID                 string `json:"owner_id"`         // Owner of the allocation
	OwnerPublicKey          string `json:"owner_public_key"` // Owner Public Key of the allocation
	Size                    int64  `json:"size"`             // difference
	Extend                  bool   `json:"extend"`
	AddBlobberId            string `json:"add_blobber_id"`
	AddBlobberAuthTicket    string `json:"add_blobber_auth_ticket"`
	RemoveBlobberId         string `json:"remove_blobber_id"`
	SetThirdPartyExtendable bool   `json:"set_third_party_extendable"`
	FileOptionsChanged      bool   `json:"file_options_changed"`
	FileOptions             uint16 `json:"file_options"`
}
```

| Field                         | Description                                                                                                                               |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| ID                            | The id of the allocation                                                                                                                  |
| name                          | (not used) the name of the allocation                                                                                                     |
| owner\_id                     | ClientID of the owner of the alloaction.                                                                                                  |
| owner\_public\_key            | Public Key of the owner of the allocation.                                                                                                |
| size                          | Size of the allocation.                                                                                                                   |
| extend                        | Whether the allocation should be extended.                                                                                                |
| add\_blobber\_id              | ID of the blobber to add to the allocation.                                                                                               |
| add\_blobber\_auth\_ticket    | Auth ticket of the blobber to add to the allocation.                                                                                      |
| remove\_blobber\_id           | ID of the blobber to remove from the allocation.                                                                                          |
| read\_price\_range            | Range of read price offer for the blobbers chosen for the allocation (Reads in Züs are free!).                                            |
| write\_price\_range           | Range of write price offer for the blobbers chosen for the allocation.                                                                    |
| set\_third\_party\_extendable | Set the allocation to be extendable by third party, meaning its size can be increased by a client other than the owner of the allocation. |
| file\_options\_changed        | Whether file option flags are changed.                                                                                                    |
| file\_options                 | File option flags mask which control permissions of the files that belong to the allocation.                                              |

#### `finalize_allocation`

Finalize an expired allocation by allocation owner or one of blobbers of the allocation. It moves all tokens have to be moved between pools and empties write pool moving left tokens to the client. It requires the following input parameters:

```go
AllocationID string `json:"allocation_id"`
```

#### `cancel_allocation`

Cancel the allocation before its expiry date. It moves all tokens have to be moved between pools and empties write pool moving left tokens to the client, it also deducts a cancelation fee mentioned in the [Allocations](https://docs.zus.network/zus-docs/system-overview/storage/protocol/allocations) page. It required the following input parameters:

```go
AllocationID string `json:"allocation_id"`
```