Permissions

https://github.com/BitBadges/bitbadgeschain/blob/master/proto/badges/permissions.proto

syntax = "proto3";
package badges;

import "google/protobuf/any.proto";
import "badges/balances.proto";
import "badges/address_lists.proto";
import "gogoproto/gogo.proto";

option go_package = "github.com/bitbadges/bitbadgeschain/x/badges/types";


/* 
  CollectionPermissions defines the permissions for the collection (i.e., what the manager can and cannot do).

  There are five types of permissions for a collection: ActionPermission, TimedUpdatePermission, TimedUpdateWithBadgeIdsPermission, BadgeIdsActionPermission, and CollectionApprovalPermission.

  The permission type allows fine-grained access control for each action.
  - ActionPermission: defines when the manager can perform an action.
  - TimedUpdatePermission: defines when the manager can update a timeline-based field and what times of the timeline can be updated.
  - TimedUpdateWithBadgeIdsPermission: defines when the manager can update a timeline-based field for specific tokens and what times of the timeline can be updated.
  - BadgeIdsActionPermission: defines when the manager can perform an action for specific tokens
  - CollectionApprovalPermission: defines when the manager can update the transferability of the collection and what transfers can be updated vs. locked.

  Note there are a few different times here which could get confusing:
  - timelineTimes: the times when a timeline-based field is a specific value
  - permanentlyPermitted/ForbiddenTimes - the times that a permission can be performed
  - transferTimes - the times that a transfer occurs
  - ownershipTimes - the times when a token is owned by a user

  The permitted/permanentlyForbiddenTimes are used to determine when a permission can be executed.
  Once a time is set to be permitted or forbidden, it is PERMANENT and cannot be changed.
  If a time is not set to be permitted or forbidden, it is considered NEUTRAL and can be updated but is ALLOWED by default.

  IMPORTANT: We take first-match only for the permissions. This means that if you forbid time T in array index 0 and permit time T in index 1, 
  we will only check the first permission (forbid time T) and not the second permission (permit time T).
*/
message CollectionPermissions {
  // Permissions related to deleting the collection.
  repeated ActionPermission canDeleteCollection = 1;

  // Permissions related to archiving the collection.
  repeated TimedUpdatePermission canArchiveCollection = 2;

  // Permissions related to updating off-chain balances metadata.
  repeated TimedUpdatePermission canUpdateOffChainBalancesMetadata = 3;

  // Permissions related to updating standards for the collection.
  repeated TimedUpdatePermission canUpdateStandards = 4;

  // Permissions related to updating custom data for the collection.
  repeated TimedUpdatePermission canUpdateCustomData = 5;

  // Permissions related to updating the collection's manager.
  repeated TimedUpdatePermission canUpdateManager = 6;

  // Permissions related to updating the metadata of the collection.
  repeated TimedUpdatePermission canUpdateCollectionMetadata = 7;

  // Permissions related to creating more tokens for the collection.
  repeated BadgeIdsActionPermission canUpdateValidBadgeIds = 8;

  // Permissions related to updating token metadata for specific tokens.
  repeated TimedUpdateWithBadgeIdsPermission canUpdateBadgeMetadata = 9;

  // Permissions related to updating collection approvals.
  repeated CollectionApprovalPermission canUpdateCollectionApprovals = 10;
}

/* 
  UserPermissions defines the permissions for the user about their approvals (i.e., what the user can and cannot do).

  See CollectionPermissions for more details on the different types of permissions.

  canUpdateOutgoingApprovals and canUpdateOutgoingApprovals follow the same as the canUpdateCollectionApprovals in CollectionPermissions,
  but certain fields are removed because they are not relevant to the user.
*/
message UserPermissions {
  // Permissions related to updating the user's approved outgoing transfers.
  repeated UserOutgoingApprovalPermission canUpdateOutgoingApprovals = 1;

  // Permissions related to updating the user's approved incoming transfers.
  repeated UserIncomingApprovalPermission canUpdateIncomingApprovals = 2;

  // Permissions related to updating auto-approval settings for self-initiated outgoing transfers (whether they are allowed by default).
  repeated ActionPermission canUpdateAutoApproveSelfInitiatedOutgoingTransfers = 3;

  // Permissions related to updating auto-approval settings for self-initiated incoming transfers (whether they are allowed by default).
  repeated ActionPermission canUpdateAutoApproveSelfInitiatedIncomingTransfers = 4;

  // Permissions related to updating auto-approval settings for all incoming transfers (whether they are allowed by default).
  repeated ActionPermission canUpdateAutoApproveAllIncomingTransfers = 5;
}


/* 
  CollectionApprovalPermission defines what collection approved transfers can be updated vs. are locked.

  Each transfer is broken down to a (from, to, initiatedBy, transferTime, badgeId) tuple.
  For a transfer to match, we need to match ALL of the fields in the combination. 
  These are determined by the fromListId, toListId, initiatedByListId, transferTimes, badgeIds fields.
  AddressLists are used for (from, to, initiatedBy) which are a permanent list of addresses identified by an ID (see AddressLists). 
  
  TimelineTimes: which timeline times of the collection's approvalsTimeline field can be updated or not?
  permanentlyPermitted/ForbiddenTimes: when can the manager execute this permission?

  Ex: Let's say we are updating the transferability for timelineTime 1 and the transfer tuple ("AllWithoutMint", "AllWithoutMint", "AllWithoutMint", 10, 1000).
  We would check to find the FIRST CollectionApprovalPermission that matches this combination.
  If we find a match, we would check the permitted/forbidden times to see if we can execute this permission (default is ALLOWED).

  Ex: So if you wanted to freeze the transferability to enforce that token ID 1 will always be transferable, you could set
  the combination ("AllWithoutMint", "AllWithoutMint", "AllWithoutMint", "All Transfer Times", 1) to always be forbidden at all timelineTimes.
*/
message CollectionApprovalPermission {
  // Identifier for the sender list.
  string fromListId = 1;

  // Identifier for the recipient list.
  string toListId = 2;

  // Identifier for the initiator list (who is approved?).
  string initiatedByListId = 3;

  // Specifies the times when the transfer can occur.
  repeated UintRange transferTimes = 4;

  // Specifies the token IDs involved in the transfer.
  repeated UintRange badgeIds = 5;

  // Specifies the ownership times for the tokens in the transfer.
  repeated UintRange ownershipTimes = 6;

  // Identifier for the approvalId. You can use "All" or "!approvalId" for shorthand.
  // If you use "All", this approval will match to all approvalIds.
  // If you use "!approvalId", this approval will match to all approvalIds except for approvalId.
  // If you use "approvalId", this approval will match to only the specified approvalId and fail on all others.
  string approvalId = 9;

  // Specifies the times when this permission is permitted. Can not overlap with permanentlyForbiddenTimes.
  repeated UintRange permanentlyPermittedTimes = 10;

  // Specifies the times when this permission is forbidden. Can not overlap with permanentlyPermittedTimes.
  repeated UintRange permanentlyForbiddenTimes = 11;
}


/* 
  UserOutgoingApprovalPermission defines the permissions for updating the user's approved outgoing transfers.
*/
message UserOutgoingApprovalPermission {
  // Identifier for the recipient list.
  string toListId = 1;

  // Identifier for the initiator list (who is approved?).
  string initiatedByListId = 2;

  // Specifies the times when the transfer can occur.
  repeated UintRange transferTimes = 3;

  // Specifies the token IDs involved in the transfer.
  repeated UintRange badgeIds = 4;

  // Specifies the ownership times for the tokens in the transfer.
  repeated UintRange ownershipTimes = 5;

  // Identifier for the approvalId. You can use "All" or "!approvalId" for shorthand.
  // If you use "All", this approval will match to all approvalIds.
  // If you use "!approvalId", this approval will match to all approvalIds except for approvalId.
  // If you use "approvalId", this approval will match to only the specified approvalId and fail on all others.
  string approvalId = 8;


  // Specifies the times when this permission is permitted. Can not overlap with permanentlyForbiddenTimes.
  repeated UintRange permanentlyPermittedTimes = 9;

  // Specifies the times when this permission is forbidden. Can not overlap with permanentlyPermittedTimes.
  repeated UintRange permanentlyForbiddenTimes = 10;
}

/* 
  UserIncomingApprovalPermission defines the permissions for updating the user's approved incoming transfers.

  See CollectionApprovalPermission for more details. This is equivalent without the toListId field because that is always the user.
*/
message UserIncomingApprovalPermission {
  // Identifier for the sender list.
  string fromListId = 1;

  // Identifier for the initiator list (who is approved?).
  string initiatedByListId = 2;

  // Specifies the times when the transfer can occur.
  repeated UintRange transferTimes = 3;

  // Specifies the token IDs involved in the transfer.
  repeated UintRange badgeIds = 4;

  // Specifies the ownership times for the tokens in the transfer.
  repeated UintRange ownershipTimes = 5;

  // Identifier for the approvalId. You can use "All" or "!approvalId" for shorthand.
  // If you use "All", this approval will match to all approvalIds.
  // If you use "!approvalId", this approval will match to all approvalIds except for approvalId.
  // If you use "approvalId", this approval will match to only the specified approvalId and fail on all others.
  string approvalId = 8;

  // Specifies the times when this permission is permitted. Can not overlap with permanentlyForbiddenTimes.
  repeated UintRange permanentlyPermittedTimes = 9;

  // Specifies the times when this permission is forbidden. Can not overlap with permanentlyPermittedTimes.
  repeated UintRange permanentlyForbiddenTimes = 10;
}

/* 
  BadgeIdsActionPermission defines the permissions for updating a timeline-based field for specific tokens and specific token ownership times.
  Currently, this is only used for creating new tokens.

  Ex: If you want to lock the ability to create new tokens for badgeIds [1,2] at ownershipTimes 1/1/2020 - 1/1/2021, 
  you could set the combination (badgeIds: [1,2], ownershipTimelineTimes: [1/1/2020 - 1/1/2021]) to always be forbidden.
*/
message BadgeIdsActionPermission {
  // Specifies the token IDs involved in the transfer.
  repeated UintRange badgeIds = 1;

  // Specifies the times when this permission is permitted. Can not overlap with permanentlyForbiddenTimes.
  repeated UintRange permanentlyPermittedTimes = 2;

  // Specifies the times when this permission is forbidden. Can not overlap with permanentlyPermittedTimes.
  repeated UintRange permanentlyForbiddenTimes = 3;
}

/* 
  ActionPermission defines the permissions for performing an action.
  
  This is simple and straightforward as the only thing we need to check is the permitted/forbidden times.
*/
message ActionPermission {
  // Specifies the times when this permission is permitted. Can not overlap with permanentlyForbiddenTimes.
  repeated UintRange permanentlyPermittedTimes = 1;

  // Specifies the times when this permission is forbidden. Can not overlap with permanentlyPermittedTimes.
  repeated UintRange permanentlyForbiddenTimes = 2;
}

/* 
  TimedUpdatePermission defines the permissions for updating a timeline-based field.

  Ex: If you want to lock the ability to update the collection's metadata for timelineTimes 1/1/2020 - 1/1/2021,
  you could set the combination (TimelineTimes: [1/1/2020 - 1/1/2021]) to always be forbidden.
*/
message TimedUpdatePermission {
  // Specifies the times when this permission is permitted. Can not overlap with permanentlyForbiddenTimes.
  repeated UintRange permanentlyPermittedTimes = 1;

  // Specifies the times when this permission is forbidden. Can not overlap with permanentlyPermittedTimes.
  repeated UintRange permanentlyForbiddenTimes = 2;

  // Specifies the times when the timeline-based field is a specific value.
  repeated UintRange timelineTimes = 3;
}


/* 
  TimedUpdateWithBadgeIdsPermission defines the permissions for updating a timeline-based field for specific tokens.

  Ex: If you want to lock the ability to update the metadata for badgeIds [1,2] for timelineTimes 1/1/2020 - 1/1/2021,
  you could set the combination (badgeIds: [1,2], TimelineTimes: [1/1/2020 - 1/1/2021]) to always be forbidden.
*/
message TimedUpdateWithBadgeIdsPermission {
  // Specifies the token IDs involved in the transfer.
  repeated UintRange badgeIds = 1;

  // Specifies the times when this permission is permitted. Can not overlap with permanentlyForbiddenTimes.
  repeated UintRange permanentlyPermittedTimes = 2;

  // Specifies the times when this permission is forbidden. Can not overlap with permanentlyPermittedTimes.
  repeated UintRange permanentlyForbiddenTimes = 3;

  // Specifies the times when the timeline-based field is a specific value.
  repeated UintRange timelineTimes = 4;
}