---
# System prepended metadata

title: 'Actor Spec: VerifiedRegistry'

---

# Actor Spec: VerifiedRegistry

[Back to Master Tracking Doc](https://hackmd.io/LOZjAsz-THelSD5lWqSVlw)

## Contents

[TOC]

## At a Glance

The VerifiedRegistry actor implements a permissioned registry of "Verified Clients." When making storage deals with Verified Clients, Miners receive a bonus incentive via the StorageMarket actor.

The VerifiedRegistry actor has three primary roles:
* The `RootKey` has the permission to add `Verifiers`
* `Verifiers` have the permission to add `VerifiedClients`
* `VerifiedClients` make "Verified Deals" with Miners.

**Actor Type:**
- Singleton
    - Address: 6

**Exported Methods:**

1. Constructor
2. AddVerifier
3. RemoveVerifier
4. AddVerifiedClient
5. UseBytes
6. RestoreBytes

## State

```go=
type State struct {
	RootKey addr.Address
	Verifiers cid.Cid
	VerifiedClients cid.Cid
}
```

**`RootKey`**: The address that has the permission to add/remove new `Verifiers`
* Notes:
    * `RootKey` should be the ID address of a Multisig actor

**`Verifiers`**: A collection of addresses that have the permission to add `VerifiedClients`. `Verifiers` have their own data allowance, which is deducted from the data allowance they initialize any `VerifiedClients` with.
* Notes:
    * Cid type: HAMT, `map[Address]DataCap`

**`VerifiedClients`**: A collection of addresses that have data allowances and make Verified Deals with Miners. Data allowance is spent / recovered via the Market actor.
* Notes:
    * Cid type: HAMT, `map[Address]DataCap`

## Exported Methods

#### 1. Constructor

```go=
func (a Actor) Constructor(rt vmr.Runtime, rootKey *addr.Address) *adt.EmptyValue
```

The VerifiedRegistry constructor initializes the actor's state with a `RootKey`.

#### 2. AddVerifier

```go=
func (a Actor) AddVerifier(rt vmr.Runtime, params *AddVerifierParams) *adt.EmptyValue
```

Allows the `RootKey` to add a new `Verifier` with its own `DataCap`.

##### Parameters

```go=
type AddVerifierParams struct {
	Address   addr.Address
	Allowance DataCap
}
```

**`Address`**: The address of the new Verifier to add to the registry.
* Notes:
    * All address protocols are currently allowed.
* Requirements:
    * `Address != st.RootKey`
    * `Address` cannot be a VerifiedClient

**`Allowance`**: The total amount of bytes the new Verifier can allocate to the `VerifiedClients` it creates.
* Requirements:
    * `Allowance >= MinVerifiedDealSize`

##### Failure conditions
* Caller is not `st.RootKey`
* `params.Allowance < MinVerifiedDealSize`
* `params.Address` resolves to `st.RootKey`
* `params.Address` resolves to an existing VerifiedClient

#### 3. RemoveVerifier

```go=
func (a Actor) RemoveVerifier(rt vmr.Runtime, verifierAddr *addr.Address) *adt.EmptyValue
```

Allows the `RootKey` to remove an existing Verifier.

**`verifierAddr`**: The Verifier to be removed.

##### Failure conditions
* Caller is not `st.RootKey`
* `verifierAddr` does not exist in `st.Verifiers`

#### 4. AddVerifiedClient

```go=
func (a Actor) AddVerifiedClient(rt vmr.Runtime, params *AddVerifiedClientParams) *adt.EmptyValue
```

Allows a Verifier to add a new Verified Client with its own `DataCap`. The `DataCap` given to the new Verified Client is subtracted from the Verifier's own `DataCap`.

##### Parameters

```go=
type AddVerifiedClientParams struct {
	Address   addr.Address
	Allowance DataCap
}
```

**`Address`**: The address of the new Verified Client.
* Requirements:
    * All address protocols are allowed
    * Should not be an existing Verified Client
    * Should not be a Verifier
    * `Address != st.RootKey`

**`Allowance`**: The number of bytes worth of Verified Deals this Verified Client can make.
* Requirements:
    * `Allowance >= MinVerifiedDealSize`

##### Failure conditions
* Caller is not a Verifier
* Caller's Verifier `DataCap` is less than `params.Allowance`
* `params.Allowance < MinVerifiedDealSize`
* `params.Address` resolves to `st.RootKey`
* `params.Address` resolves to an existing Verifier
* `params.Address` resolves to an existing VerifiedClient

#### 5. UseBytes

```go=
func (a Actor) UseBytes(rt vmr.Runtime, params *UseBytesParams) *adt.EmptyValue
```

Allows the StorageMarket actor to consume bytes from a Verified Client's allowance. 
* This method is invoked when a deal provided to StorageMarket.PublishStorageDeals is marked `VerifiedDeal`.
* The StorageMarket actor should provide `UseBytes` with the exact number of bytes for which the deal in question is being made.
* Because deals published via StorageMarket.PublishStorageDeals, invocation of this method signifies that a Verified Client is using their `DataCap` allowance.

If a Verified Client has less than `MinVerifiedDealSize` allowance left after `params.DealSize` is removed, the Verified Client is removed from `st.VerifiedClients`.
* Otherwise, their `st.VerifiedClients` entry is simply updated.

##### Parameters

```go=
type UseBytesParams struct {
	Address  addr.Address
	DealSize abi.StoragePower
}
```

**`Address`**: The Verified Client whose deal was published via the StorageMarket actor
* Notes:
    * All address protocols are allowed
* Requirements:
    * Must exist within `st.VerifiedClients`

**`DealSize`**: The amount of data being consumed by the deal in question. This value is subtracted from the Verified Client's `DataCap`
* Requirements:
    * `params.Address` must have at least `DealSize` bytes in their `DataCap`

##### Failure conditions
* Caller is not the StorageMarket actor
* `params.DealSize < MinVerifiedDealSize`
* `params.Address` does not resolve to an existing VerifiedClient
* `params.Address` resolves to an existing VerifiedClient, but does not have sufficient allowance for `params.DealSize`

#### 6. RestoreBytes

```go=
func (a Actor) RestoreBytes(rt vmr.Runtime, params *RestoreBytesParams) *adt.EmptyValue
```

In the event a Verified Deal times out, the StorageMarket actor will call this method to restore the deal's bytes to the Verified Client in question.
* Invoked from StorageMarket.CronTick

##### Parameters

```go=
type RestoreBytesParams struct {
	Address  addr.Address
	DealSize abi.StoragePower
}
```

**`Address`**: The address of the Verified Client whose deal timed out.
* Notes:
    * All address protocols allowed
* Requirements:
    * `Address != st.RootKey`
    * `Address` cannot be a Verifier

**`DealSize`**: The amount of bytes being restored to the Verified Client's `DataCap`
* Requirements:
    * Must be at least `MinVerifiedDealSize`

##### Failure conditions
* Caller is not the StorageMarket actor
* `params.DealSize < MinVerifiedDealSize`
* `params.Address` resolves to `st.RootKey`
* `params.Address` resolves to an existing Verifier

---