HIP-796 (Partition Token)

services/basic_types.proto

@@ -407,6 +407,13 @@ enum TokenType {
      * different values.  Individually traced and can carry unique properties (e.g. serial number).
      */
     NON_FUNGIBLE_UNIQUE = 1;
+
+    /**
+    * A special type of token that holds a subset of the supply of a FUNGIBLE_COMMON token, or
+    * a subset of the serial numbers of a NON_FUNGIBLE_UNIQUE token. Partitions are always "children"
+    * of another token such as a FUNGIBLE_COMMON or NON_FUNGIBLE_UNIQUE token.
+    */
+    PARTITION = 2;
 }
 
 /**

services/partition_create.proto

@@ -0,0 +1,27 @@
+syntax = "proto3";
+
+package proto;
+
+
+/**
+ * Create a new partition type on a token. After the entity is created, the TokenID for it is in
+ * the receipt.
+ */
+ message TokenCreatePartitionDefinitionTransactionBody {
+    /**
+     * The token (either FUNGIBLE_COMMON or NON_FUNGIBLE_UNIQUE) that this partition is a part of.
+     */
+    TokenID parent_token_id = 1;
+
+    /**
+     * The publicly visible name of the partition. The partition name is specified as a Unicode
+     * string. Its UTF-8 encoding cannot exceed 100 bytes, and cannot contain the 0 byte (NUL).
+     * This name is not unique within the ledger.
+     */
+    string name = 2;
+
+    /**
+     * The memo associated with the partition (UTF-8 encoding max 100 bytes)
+     */
+    string memo = 3;
+}

services/partition_delete.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package proto;
+
+
+
+// Do we need to add partition_definition_id
+
+/**
+ * Marks a token partition as deleted, though it will remain in the ledger.
+ * The operation must be signed by the specified partition key of the parent Token. If
+ * the partition key is not set, the Transaction will result in TOKEN_IS_IMMUTABlE.
+ * Once deleted update, freeze, unfreeze, grant kyc, revoke kyc and token transfer
+ * transactions will resolve to TOKEN_WAS_DELETED.
+ */
+ message TokenDeletePartitionDefinitionTransactionBody {
+    /**
+     * The token partition to be deleted. If an invalid token is specified, the transaction will
+     * result in INVALID_TOKEN_ID
+     */
+    TokenID token = 1;
+
+}

services/partition_update.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+
+package proto;
+
+
+
+/**
+ * At consensus, updates an already created token partition to the given values.
+ */
+ message TokenUpdatePartitionTransactionBody {
+    /**
+     * The Token partition to be updated
+     */
+    TokenID token = 1;
+
+    /**
+     * The new publicly visible name of the token. The token name is specified as a Unicode string.
+     * Its UTF-8 encoding cannot exceed 100 bytes, and cannot contain the 0 byte (NUL).
+     */
+    string name = 2;
+
+    /**
+     * If set, the new memo to be associated with the token (UTF-8 encoding max 100 bytes)
+     */
+    google.protobuf.StringValue memo = 3;
+}

services/schedulable_transaction_body.proto

@@ -72,6 +72,13 @@ import "token_unpause.proto";
 import "schedule_delete.proto";
 import "util_prng.proto";
 
+
+import "partition_create.proto";
+import "partition_update.proto";
+import "partition_delete.proto";
+import "token_lock.proto";
+import "token_unlock.proto";
+
 /**
  * A schedulable transaction. Note that the global/dynamic system property
  * <tt>scheduling.whitelist</tt> controls which transaction types may be scheduled. As of Hedera
@@ -283,5 +290,36 @@ message SchedulableTransactionBody {
      * Generates a pseudorandom number.
      */
     UtilPrngTransactionBody util_prng = 40;
+
+
+
+    /**
+      Create new partition
+     */
+
+     TokenCreatePartitionDefinitionTransactionBody partitionCreation = 41;
+
+     /**
+       Update the partition
+      */
+
+     TokenUpdatePartitionTransactionBody partitionUpdate = 42;
+
+     /**
+       Delete the partition
+      */
+
+     TokenDeletePartitionDefinitionTransactionBody partitionDeletion = 43;
+
+     /**
+       Lock the token
+      */
+     TokenLockTransactionBody tokenLock = 44;
+
+     /**
+       Unlock the token
+      */
+
+     TokenUnlockTransactionBody tokenUnlock = 45;
   }
 }

services/token_create.proto

@@ -198,4 +198,56 @@ message TokenCreateTransactionBody {
      * If Empty the token pause status defaults to PauseNotApplicable, otherwise Unpaused.
      */
     Key pause_key = 22;
+
+
+
+    /**
+   * The key which can lock, unlock, or transfer locked tokens in an account. Each fungible token
+   * balance of a token-definition with a lock_key will have both a balance, and a quantity of
+   * locked tokens, where the quantity of locked tokens may be 0. If this key is desired, it
+   * must be set at the time the token-definition is created. It can only be set for token
+   * definitions with a TokenType of FUNGIBLE_COMMON and NON_FUNGIBLE_UNIQUE. If set, it may be updated, but only if the
+   * update transaction is signed both by the lock key and the new lock key. Once null, it
+   * cannot be set again.
+   *
+   * If set on a token-definition that also sets the partition_key, then the lock_key may also be
+   * used to lock balances on those partitions.
+   */
+  Key lock_key = 23;
+
+  /**
+   * The key which can create, update, and delete partitions of this token type. If this key is
+   * desired, it must be set at the time the token-definition is created. It is applicable to both
+   * FUNGIBLE_COMMON and NON_FUNGIBLE_UNIQUE token types. If set, it may be updated, but only if
+   * the update transaction is signed both by the old partition key and the new partition key.
+   * Once null, it cannot be set again.
+   */
+  Key partition_key = 24;
+
+  /**
+   * The key which can move balances from the token type's supply into any partition of any user,
+   * or move balance from one partition to another of different types, either in the same account,
+   * or in different accounts.
+   *
+   * For example, if two users both have partitions "tranche-A" and "tranche-B", then either user
+   * could move tokens from their "tranche-A" to the other user's "tranche-A", or from their
+   * "tranche-B" to the other user's "tranche-B", but they cannot transfer from their "tranche-A"
+   * to the other user's "tranche-B", or from their "tranche-A" to their own "tranche-B". That is,
+   * under normal circumstances, you can transfer funds between partitions of the same type, but not
+   * between partitions of different types.
+   *
+   * However, a transaction signed by this key *can* transfer funds between partitions of different
+   * types, either for the same user, or for different users. So user Alice can transfer balance
+   * from her "Tranche-A" to user Bob's "Tranche-B", if the transaction is signed both by Alice,
+   * and by the partition-move-key. In addition, balance may be transferred from Alice's "Tranche-A"
+   * into Alice's "Tranche-B", if the transaction is signed by the partition-move-key. Transferring
+   * balances across partitions in the user's account does not require the user to sign the
+   * transaction.
+   *
+   * If this key is desired, it must be set at the time the token-definition is created. It is
+   * applicable to both FUNGIBLE_COMMON and NON_FUNGIBLE_UNIQUE token types. If set, it may be
+   * updated, but only if the update transaction is signed both by the old partition move key
+   * and the new partition move key. Once null, it cannot be set again.
+   */
+  Key partition_move_key = 25;
 }

services/token_delete.proto

@@ -34,6 +34,9 @@ import "basic_types.proto";
  * admin key is not set, Transaction will result in TOKEN_IS_IMMUTABlE.
  * Once deleted update, mint, burn, wipe, freeze, unfreeze, grant kyc, revoke
  * kyc and token transfer transactions will resolve to TOKEN_WAS_DELETED.
+ * 
+ * A token cannot be deleted if it has any partition definitions that are not
+ * also deleted. In that case, the transaction will resolve to TOKEN_PARTITIONS_STILL_EXIST.
  */
 message TokenDeleteTransactionBody {
     /**

services/token_lock.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package proto;
+
+
+
+/**
+ * Lock a certain amount of tokens in an account. The TokenID must refer either to a
+ * FUNGIBLE_COMMON token type, or a partition of such a token type.
+ */
+ message TokenLockTransactionBody {
+    AccountID account_id = 1;
+    TokenID token_id = 2; // token-definition-id or partition-definition-id
+    oneOf amountOrSerialNumber {
+        int64 amount = 3; // if token-definition is FUNGIBLE_COMMON
+        int64 serialNumber = 4; // if the token-definition is NON_FUNGIBLE_UNIQUE
+    }
+}

services/token_service.proto

@@ -128,4 +128,32 @@ service TokenService {
 
     //  Unpause the token
     rpc unpauseToken (Transaction) returns (TransactionResponse);
+
+
+
+  /**
+   * Locks an amount of the token in a user's account or partition of their account.
+   */
+  rpc lockToken (Transaction) returns (TransactionResponse);
+
+  /**
+   * Unlocks an amount of the token in a user's account or partition of their account.
+   */
+  rpc unlockToken (Transaction) returns (TransactionResponse);
+
+  /**
+   * Creates a new partition definition on a token definition. After the entity is created,
+   * the TokenID for it is in the receipt.
+   */
+  rpc createTokenPartitionDefinition (Transaction) returns (TransactionResponse);
+
+  /**
+   * Updates an already created token partition definition to the given values.
+   */
+  rpc updateTokenPartitionDefinition (Transaction) returns (TransactionResponse);
+
+  /**
+   * Marks a token partition definition as deleted, though it will remain in the ledger.
+   */
+  rpc deleteTokenPartitionDefinition (Transaction) returns (TransactionResponse);
 }

services/token_unlock.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package proto;
+
+
+
+
+/**
+ * Unlock a certain amount of tokens in an account. The TokenID must either refer to a
+ * FUNGIBLE_COMMON token type, or a partition of such a token type.
+ */
+ message TokenUnlockTransactionBody {
+    AccountID accoun_id = 1;
+    TokenID token_id = 2; // token-definition-id or partition-definition-id
+    oneOf amountOrSerialNumber {
+        int64 amount = 3; // if token-definition is FUNGIBLE_COMMON
+        int64 serialNumber = 4; // if the token-definition is NON_FUNGIBLE_UNIQUE
+    }
+}

services/token_update.proto

@@ -142,4 +142,27 @@ message TokenUpdateTransactionBody {
      * transaction will resolve to TOKEN_HAS_NO_PAUSE_KEY
      */
     Key pause_key = 15;
+
+
+
+    /**
+   * The key which can lock, unlock, or transfer locked tokens in an account. If the Token does not
+   * currently have a lock key, transaction will resolve to TOKEN_HAS_NO_LOCK_KEY
+   */
+    Key lock_key = 16;
+
+    /**
+     * The key which can create, update, and delete partitions of this token type. If the Token does
+     * not currently have a partition key, transaction will resolve to TOKEN_HAS_NO_PARTITION_KEY
+     */
+    Key partition_key = 17;
+
+    /**
+     * The key which can move balances from the token type's supply into any partition of any user,
+     * or move balance from one partition to another of different types, either in the same account,
+     * or in different accounts.
+     * If the Token does not currently have a partition move key, transaction will resolve to
+     * TOKEN_HAS_NO_PARTITION_MOVE_KEY
+     */
+    Key partition_move_key = 18;
 }

services/transaction_body.proto

@@ -84,6 +84,14 @@ import "schedule_sign.proto";
 import "node_stake_update.proto";
 import "util_prng.proto";
 
+
+import "partition_create.proto";
+import "partition_update.proto";
+import "partition_delete.proto";
+import "token_lock.proto";
+import "token_unlock.proto";
+
+
 /**
  * A single transaction. All transaction types are possible here.
  */
@@ -350,5 +358,37 @@ message TransactionBody {
      * Generates a pseudorandom number.
      */
     UtilPrngTransactionBody util_prng = 52;
+
+
+
+    /**
+      Create new partition
+     */
+
+    TokenCreatePartitionDefinitionTransactionBody partitionCreation = 53;
+
+    /**
+      Update the partition
+     */
+
+    TokenUpdatePartitionTransactionBody partitionUpdate = 54;
+
+    /**
+      Delete the partition
+     */
+
+    TokenDeletePartitionDefinitionTransactionBody partitionDeletion = 55;
+
+    /**
+      Lock the token
+     */
+    TokenLockTransactionBody tokenLock = 55;
+
+    /**
+      Unlock the token
+     */
+
+    TokenUnlockTransactionBody tokenUnlock = 56;
+
   }
 }

services/transaction_receipt.proto

@@ -164,4 +164,12 @@ message TransactionReceipt {
      * the newly created NFTs
      */
     repeated int64 serialNumbers = 14;
+
+
+
+    /**
+     * If during CreateToken, a partition_key is specified but no supply_key is specified, then a single initial
+     * partition is created in addition to the token definition. This is the ID of that partition definition.
+     */
+     TokenID initialPartitionID = 15;
 }