Actor Spec: VerifiedRegistry

Back to Master Tracking Doc

Contents

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
Select a repo