# 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

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

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

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

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

##### Parameters

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

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

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

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

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

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

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

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

---