atomic object update bep

BEPs/BEP-346.md

@@ -0,0 +1,120 @@
+<pre>
+  BEP: 346
+  Title: Greenfield Atomic Object Update
+  Status: Under progress
+  Type: Standards
+  Created: 2024-01-18
+</pre>
+
+# BEP-346: Greenfield Atomic Object Update
+
+<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [BEP-335: Simplify Storage Provider Exit](#bep-335-simplify-storage-provider-exit)
+  - [1. Summary](#1-summary)
+  - [2. Motivation](#2-motivation)
+  - [3. Status](#3-status)
+  - [4. Specification](#4-specification)
+    - [4.1 Requirements](#41-requirements)
+    - [4.2 Implementation](#42-implementation)
+    - [4.2.1 Change To Current Model](#421-change-to-current-model)
+    - [4.2.2 New Model And Message](#422-new-model-and-message)
+      - [4.3.1 Data heal process](#431-data-heal-process)
+    - [4.4 The SP Forced Exit Procedure](#44-the-SP-forced-exit-procedure)
+    - [4.5 Concurrent SP Exit](#45-concurrent-SP-exit)
+<!-- /code_chunk_output -->
+
+## 1. Summary
+This proposal seeks to enhance the efficiency and reliability of object modifications in the Greenfield network by introducing 
+atomic object updates. This update will improve the management of objects in Greenfield by ensuring atomicity, and consistency.
+
+## 2. Motivation
+Currently, users are required to delete and recreate objects in order to replace their content in Greenfield. 
+This process leads to the loss of associated policies and change to the object's ID, requiring users to re-enforce policies 
+and trigger any mirroring processes again, refer to [Resource Mirror](https://docs.bnbchain.org/greenfield-docs/docs/faq/mirroring-faqs/#what-is-mirroring) for more details.  The motivation behind this proposal is to address these issues and provide a 
+more efficient and seamless object update process.
+
+## 3. Status
+This BEP is under progress
+
+## 4. Specification
+
+### 4.1 Requirements
+- Atomicity: Atomicity refers to the ability to ensure that updates to an object either all succeed or all fail, guaranteeing that the object remains in a consistent state.
+- Consistency: Ensures that an object remains in a valid and predictable state after a successful update. Object metadata on the Greenfield Blockchain and the data stored on the Storage Provider will be maintained to ensure users can retrieve correct object data at any state of the updating process.
+
+### 4.2 Implementation
+
+#### 4.2.1. Change To Current Model
+- [ObjectInfo](https://docs.bnbchain.org/greenfield-docs/docs/guide/storage-provider/modules/common/proto/#objectinfo-proto):
+  ObjectInfo is used for object metadata stored in Greenfield. Below fields are added.
+  - `updating`: Indicate whether an object is being updated. It means the user has initiated an update request, and the SP has not committed the change to Greenfield yet.
+  - `updated_at`: The timestamp that the user initiated to update the object. The storage price is determined by it, and a new store fee needs to be calculated.
+  - `version`: The current version of the object. It can be used to locate the correct version of object data in SP.
+
+#### 4.2.1. New Model And Message
+- `ShadowObjectInfo`: It is introduced to store user updated object metadata, the life cycle for a shadowObjectInfo is 
+  started when users trigger the update request on Greenfield, once SP has the updated object data stored and confirm 
+  on Greenfield, it will be removed.
+  - `operator`: The account who initiates update object request, can be the owner or any account that has been granted permission to update object content.
+  - `id`: The id of the object, it is the same as the id in ObjectInfo.
+  - `payload_size`: The updated object size.
+  - `checksums`: The updated checksums of pieces stored in storage providers.
+  - `updated_at`: The timestamp that user initiated to update object request.
+  - `version`: The expected next version of the object.
+- `MsgUpdateObjectContent`: A new message for users' update object content transaction. The new object's payload_size,
+  checksums along with approval from primary SP's approval need to be specifcied.
+```protobuf
+message MsgUpdateObjectContent {
+  option (cosmos.msg.v1.signer) = "operator";
+  // operator defines the account address of object uploader
+  string operator = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+  // bucket_name defines the name of the bucket where the object is stored.
+  string bucket_name = 2;
+  // object_name defines the name of object
+  string object_name = 3;
+  // payload_size defines size of the object's payload
+  uint64 payload_size = 4;
+  // content_type defines a standard MIME type describing the format of the object.
+  string content_type = 5;
+  // primary_sp_approval defines the approval info of the primary SP which indicates that primary sp confirm the user's request.
+  common.Approval primary_sp_approval = 6;
+  // expect_checksums defines a list of hashes which was generate by redundancy algorithm.
+  repeated bytes expect_checksums = 7;
+}
+```
+
+## 4.3 Workflow
+
+The steps to update an object are illustrated below. To users, it is similar when compared to the current create-upload object process.
+
+![](./assets/BEP-346/workflow.png)
+
+1. Users obtain approval from the primary SP where the object is stored and send the transaction to Greenfield with the 
+   message MsgUpdateObjectContent. This stores the updated object metadata via shadowObjectInfo and flags the object as 
+   updating without changing the objectInfo on-chain.
+
+2. Users upload the updated object to the primary SP. The SP will validate if the object can be updated and authenticate 
+   the user's account permission.
+
+3. The SP should keep the original and updated object data simultaneously, version in ObjectInfo or ShadowObjectInfo is 
+   also used to identify the object data persistence to ensure there is no conflict. Users should be able to `GET` 
+   the original object data at this moment as the version field has not changed.
+
+4. The primary SP sends the sealing object transaction to the Greenfield blockchain, changes to objectInfo will take effect according 
+   to meta stored in shadowObjectInfo with version increment. Users will be able to GET the updated object data.
+   In the case where SP fails to seal the object after retries, it would send tx RejectSealobject to Greenfield to reject 
+   the users request. The metadata shadowObjectInfo will be removed from chain, updated object data will be removed from SP.
+
+## 4.4 Fees & User Charges
+The current policy regarding user charges is as follows: When users create and upload an object, a minimum of 6 months 
+storage fee is reserved on Greenfield. This fee is then paid to the Storage Providers' accounts through stream payment. 
+If objects are stored for more than 6 months, the storage fee will be calculated based on the actual time.
+This rule applies to updating objects as well. When users update an object, Greenfield will deduct the payment for the 
+original object from users’s account and reserve at least 6 months of storage fee for the updated object, taking into 
+account the new object size. It's important for users to be aware that each time an object is updated, there will be 
+associated costs.
+
+