Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HIP-796 (Partition Token) #307

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions services/basic_types.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

/**
Expand Down
27 changes: 27 additions & 0 deletions services/partition_create.proto
Original file line number Diff line number Diff line change
@@ -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;
}
23 changes: 23 additions & 0 deletions services/partition_delete.proto
Original file line number Diff line number Diff line change
@@ -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;

}
26 changes: 26 additions & 0 deletions services/partition_update.proto
Original file line number Diff line number Diff line change
@@ -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;
}
38 changes: 38 additions & 0 deletions services/schedulable_transaction_body.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;
}
}
52 changes: 52 additions & 0 deletions services/token_create.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
3 changes: 3 additions & 0 deletions services/token_delete.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand Down
18 changes: 18 additions & 0 deletions services/token_lock.proto
Original file line number Diff line number Diff line change
@@ -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
}
}
28 changes: 28 additions & 0 deletions services/token_service.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
19 changes: 19 additions & 0 deletions services/token_unlock.proto
Original file line number Diff line number Diff line change
@@ -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
}
}
23 changes: 23 additions & 0 deletions services/token_update.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
40 changes: 40 additions & 0 deletions services/transaction_body.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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;

}
}
8 changes: 8 additions & 0 deletions services/transaction_receipt.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}