Skip to content

Commit

Permalink
init doc
Browse files Browse the repository at this point in the history
  • Loading branch information
fynn-0xc committed Feb 28, 2023
1 parent ea04636 commit de5b6f0
Show file tree
Hide file tree
Showing 6 changed files with 735 additions and 8 deletions.
195 changes: 195 additions & 0 deletions docs/architecture/04-storage_provider_management.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
# Storage Provider Management

## Abstract

SPs play a different role from Greenfield validators, although the same organizations or individuals can run both SPs
and validators if they follow all the rules and procedures to get elected.

The SP module is responsible for managing and maintaining several storage providers in the BNB Greenfield Decentralize
Storage.

- Metadata: The basic information about the SP, including address, tokens, status, and so on.
- Deposit: Each SP who wants to join the storage network should stake tokens to ensure that it can provide storage
services normally
- Slash: The data stored on the SP will be challenged from time to time. When a challenge is successful, the SP will be
slashed, and deduct some tokens.
- Reputation: We will introduce a reputation system to evaluate SP's service quality. Users can choose which SP to store
data based on reputation score.
- Exit: The storage provider has the right to out of the service and gets back the staked tokens. When the storage
provider has insufficient staked tokens or the reputation score is too low, InscriptionChain will force the storage
provider to exit the storage network.

## Key Workflow

### Join the network

SPs have to register themselves first by depositing on the Greenfield blockchain as their "Service Stake". Greenfield
validators will go through a dedicated governance procedure to vote for the SPs of their election. SPs are encouraged to
advertise their information and prove to the community their capability, as SPs have to provide a professional storage
system with high-quality SLA.

It will takes several transactions to join the greenfield storage network for storage provider.

1. The funding account of sp should grant the governance module account to deduct tokens for staking.
2. The sp submit a `CreateStorageProvider` proposal to governance module
3. Deposit enough tokens for this proposal
4. The validators should vote for this proposal. Pass or reject.
5. When enough validators vote the proposal, then the storage provider will be auto created on chain.

### Leave the network

When the SPs join and leave the network, they have to follow a series of actions to ensure data redundancy for the
users; otherwise, their "Service Stake" will be fined. This is achieved through the data availability challenge and
validator governance votes.

### Reputation

We'll introduce a reputation system for storage provider to evaluate the quality of service of SP.

## State

### StorageProvider

Storage Provider can be ont of several statuses:

* `STATUS_IN_SERVICE`: The sp is in service. it can serve user's Create/Upload/Download request.
* `STATUS_IN_JAILED`: The sp was been slashed many times, and its deposit tokens is insufficient.
* `STATUS_GRACEFUL_EXITING`: The SP is exiting gracefully. All the object stored in it will be shifted to another sp.
* `STATUS_OUT_OF_SERVICE`: The SP is out of service. it can be a short-lived service unavailable. Users are unable
to store or get payload data on it.

Storage providers metadata should be primarily stored and accessed by the `OperatorAddr`, an EIP712 account address
for the operator of the storage provider. Three additional indices are maintained per storage provider metadata in
order to fulfill required lookups for SealObject/Deposit/Slash/GetApproval.

* StorageProvider: `0x21 | OperatorAddr -> ProtocolBuffer(StorageProvider)`
* StorageProviderByFundingAddress: `0x22 | FundingAddress -> OperatorAddr`
* StorageProviderBySealAddress: `0x23 | SealAddress -> OperatorAddr`
* StorageProviderByApprovalAddress: `0x24 | ApprovalAddress -> OperatorAddr`

Each storage provider's state is stored in a `StorageProvider` struct.

```protobuf
message StorageProvider {
option (gogoproto.equal) = false;
option (gogoproto.goproto_stringer) = false;
// operator_address defines the address of the sp's operator; It also is the unqiue index key of sp.
string operator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// fund_address is the account address of the storage provider for deposit, remuneration.
string funding_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// seal_address is the account address of the storage provider for sealObject
string seal_address = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// approval_address is the account address of the storage provider for ack CreateBuclet/Object.
string approval_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// total_deposit define the deposit token
string total_deposit = 5 [
(cosmos_proto.scalar) = "cosmos.Int",
(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
(gogoproto.nullable) = false
];
// status is the status of sp, which can be (in_service/read_only_service/graceful_exiting/out_of_service)
Status status = 6;
// endpoint is the service address of the storage provider
string endpoint = 7;
// description defines the description terms for the validator.
Description description = 8 [(gogoproto.nullable) = false];
}
```

### Params
Params is a module-wide configuration structure that stores system parameters
and defines overall functioning of the sp module.

```protobuf
// Params defines the parameters for the module.
message Params {
option (gogoproto.equal) = true;
option (gogoproto.goproto_stringer) = false;
// deposit_denom defines the staking coin denomination.
string deposit_denom = 1;
// min_deposit_amount defines the minimum deposit amount for storage providers.
string min_deposit = 2 [
(cosmos_proto.scalar) = "cosmos.Int",
(gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
(gogoproto.nullable) = false
];
}
```

### Deposit Pool

Sp module use its module account to manage all the staking tokens which deposit by storage providers.

## Message

### MsgCreateStorageProvider

A storage provider is created using the `MsgCreateProvider` messages.

```protobuf
message MsgCreateStorageProvider {
option (cosmos.msg.v1.signer) = "creator";
string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
Description description = 2 [(gogoproto.nullable) = false];
string sp_address = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string funding_address = 4 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string seal_address = 5 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string approval_address = 6 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string endpoint = 7;
cosmos.base.v1beta1.Coin deposit = 8 [(gogoproto.nullable) = false];
}
```

This message is expected to fail if:

* another storage provider with this operator/seal/funding/approval address is already registered.
* the initial deposit tokens are of a denom not specified as the deposit denom of sp module
* the deposit tokens is insufficient

### MsgEditStorageProvider

The metadata of a storage provider can be edit using `MsgEditStorageProvider` messages.

```protobuf
// MsgEditStorageProvider defines a SDK message for editing an existing sp.
message MsgEditStorageProvider {
option (cosmos.msg.v1.signer) = "sp_address";
string sp_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string endpoint = 2;
Description description = 3 [(gogoproto.nullable) = false];
}
```

This message is expected to fail if:

* the storage provider is not exist
* the description fields are too large

### MsgDeposit

When the deposit tokens of a storage provider is insufficient, it can use `MsgDeposit` messages to resupply the
deposit tokens.

```protobuf
// MsgDeposit defines a SDK message for deposit token for sp.
message MsgDeposit {
option (cosmos.msg.v1.signer) = "creator";
// creator is the msg signer, it should be sp address or sp's fund address
string creator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// sp_address is the operator address of sp
string sp_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// deposit is a mount of token which used to deposit for SP
cosmos.base.v1beta1.Coin deposit = 3 [(gogoproto.nullable) = false];
}
```

This message is expected to fail if:

* the storage provider is not exist
* the deposit tokens are of a denom not specified as the deposit denom of sp module

Loading

0 comments on commit de5b6f0

Please sign in to comment.