BEP-334: Greenfield CrossChain Permission Module (bnb-chain#334)

BEPs/BEP-334.md

@@ -0,0 +1,105 @@
+<pre>
+  BEP: 334
+  Title: Greenfield CrossChain Permission Module
+  Status: Draft
+  Type: Standards
+  Created: 2023-12-06
+</pre>
+
+# BEP-334: Greenfield CrossChain Permission Module
+
+<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [BEP-334: Greenfield CrossChain Permission Module](#bep-334-greenfield-crosschain-permission-module)
+    - [1. Summary](#1-summary)
+    - [2. Abstract](#2-abstract)
+    - [3. Motivation](#3-motivation)
+    - [4. Specification](#4-specification)
+      - [4.1 Definitions](#41-definitions)
+      - [4.2 Interface](#42-interface)
+        - [4.2.1 Create Policy](#421-create-policy)
+        - [4.2.2 Delete Policy](#422-delete-policy)
+    - [5. License](#5-license)
+
+<!-- /code_chunk_output -->
+
+
+
+## 1. Summary
+Currently, Greenfield supports creating buckets and groups from the smart contracts deployed on BSC/opBNB. This means that the owner of a bucket can be a contract address. However, contract addresses cannot upload objects or put policies under the bucket, resulting in empty buckets owned by smart contracts.
+To address this issue, we are going to introduce the cross-chain permission module. With this BEP, smart contracts can grant EOA addresses the ability to upload objects under their buckets, and even support additional functions.
+
+## 2. Abstract
+Greenfield CrossChain Permission Module has several significant differences and improvements compared to current implementations:
+- BSC/opBNB account is allowed to put policy for Greenfield resources.
+- BSC/opBNB account is allowed to disable policy for Greenfield resources. 
+
+## 3. Motivation
+In the current framework, Users can use the "policy put [RESOURCE-URL]" command to assign read/write permissions to other accounts or groups (called principal) for GreenField resource, such as the permission to delete objects. 
+Users could only change the permissions on Greenfield. The proposal allows Greenfield users to change the read/write permissions of GreenField resource directly on the BSC/opBNB network.
+
+## 4. Specification
+### 4.1 Definitions
+- PermissionHub Contract: A new middle-layer contract to request permission changes from BSC/opBNB to Greenfield
+
+### 4.2 Interface
+#### 4.2.1 Create Policy
+The interface to create policy is as follows:
+**function createPolicy(bytes calldata _data, ExtraData memory _extraData) external;**
+`_data` is the protobuf encoded bytes of the struct MsgPutPolicy as follows:
+```golang
+type Policy struct {
+	Id Uint `protobuf:"bytes,1,opt,name=id,proto3,customtype=Uint" json:"id"`
+	Principal *Principal `protobuf:"bytes,2,opt,name=principal,proto3" json:"principal,omitempty"`
+	ResourceType resource.ResourceType `protobuf:"varint,3,opt,name=resource_type,json=resourceType,proto3,enum=greenfield.resource.ResourceType" json:"resource_type,omitempty"`
+	ResourceId Uint `protobuf:"bytes,4,opt,name=resource_id,json=resourceId,proto3,customtype=Uint" json:"resource_id"`
+	Statements []*Statement `protobuf:"bytes,5,rep,name=statements,proto3" json:"statements,omitempty"`
+	ExpirationTime *time.Time `protobuf:"bytes,6,opt,name=expiration_time,json=expirationTime,proto3,stdtime" json:"expiration_time,omitempty"`
+}
+
+type Statement struct {
+    Effect Effect `json:"effect,omitempty"`
+    Actions []ActionType `json:"actions,omitempty"`
+    Resources []string `protobuf:"bytes,3,rep,name=resources,proto3" json:"resources,omitempty"`
+    ExpirationTime *time.Time `json:"expiration_time,omitempty"`
+    LimitSize *common.UInt64Value `json:"limit_size,omitempty"`
+}
+```
+
+For `Policy`:
+`Id` is an unique u256 sequence for each policy. It also be used as NFT tokenID.
+`Principal` defines the roles that can grant permissions. Currently, it can be account or group.
+`Resource` defines a greenfield standard resource name that can be generated by GRN structure.
+`Statements` defines a list of individual statement which describe the detail rules of policy.
+`ExpirationTime` defines the whole expiration time of all the statements.
+
+For Statement:
+`Effect` define the impact of permissions, which can be `Allow`/`Deny`.
+`ActionType` defines the operation type you can act on. greenfield defines a set of permission that you can specify in a permissionInfo. see `ActionType` enum for detail.
+`ExpirationTime` defines how long the permission is valid. If not explicitly specified, it means it will not expire.
+`LimitSize` defines the total data size that is allowed to operate. If not explicitly specified, it means it will not limit.
+
+
+ExtraData is as follows:
+```golang
+struct ExtraData {
+    address appAddress;     // callback app address 
+    address refundAddress;  // refund callback gas fee
+    bytes callbackData;     // calldata for callback
+}
+```
+`appAddress` defines the callback contract after receiving the cross-chain ack package.
+`refundAddress` defines the refund address to receive the unspent callback gas fee.
+`callbackData` defines the calldata for the callback call.
+
+#### 4.2.2 Delete Policy
+The interface to delete policy is as follows:
+**function deletePolicy(uint256 policyId) external payable returns (bool);**
+
+`policyId` is generated while creating policy. Only the owner of the policy can delete it.
+The deletion of a nonexistent policy will fail on GreenField.
+
+## 5. License
+The content is licensed under [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

README.md

@@ -51,6 +51,7 @@ Here is the list of subjects of BEPs:
 | [BEP-319](./BEPs/BEP-319.md) | Optimize the incentive mechanism of the Fast Finality feature | Standards | Candidate |
 | [BEP-323](./BEPs/BEP323.md)  | Bundle Format for Greenfield                                  | Standards | Enabled   |
 | [BEP-333](./BEPs/BEP333.md)  | BNB Chain Fusion                                              | Standards | Candidate |
+| [BEP-334](./BEPs/BEP-334.md) | Greenfield CrossChain Permission Module                       | Standards | Draft     |
 | [BEP-336](./BEPs/BEP-336.md) | Implement EIP-4844: Shard Blob Transactions                   | Standards | Draft     |
 | [BEP-342](./BEPs/BEP-342.md) | Implement EIP-5656: MCOPY                                     | Standards | Candidate |
 | [BEP-343](./BEPs/BEP-343.md) | Implement EIP-1153: Transient storage opcodes                 | Standards | Candidate |