From 0e65def8c905799d529b6b790233248554d6bef0 Mon Sep 17 00:00:00 2001 From: Rob Walworth Date: Wed, 15 May 2024 12:57:57 -0500 Subject: [PATCH 1/3] docs: use signerKey to specify when any additional keys should sign a transaction Signed-off-by: Rob Walworth --- .../accountCreateTransaction.md | 61 ++++++++++--------- 1 file changed, 33 insertions(+), 28 deletions(-) diff --git a/test-specifications/crypto-service/accountCreateTransaction.md b/test-specifications/crypto-service/accountCreateTransaction.md index bd49de9..a9d7c31 100644 --- a/test-specifications/crypto-service/accountCreateTransaction.md +++ b/test-specifications/crypto-service/accountCreateTransaction.md @@ -30,19 +30,19 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api ### Input Parameters -| Parameter Name | Type | Required/Optional | Description/Notes | -|---------------------------|--------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| key | string | optional | DER-encoded hex string representation for private or public keys. Keylists and threshold keys are the hex of the serialized protobuf bytes. | -| initialBalance | int64 | optional | Units of tinybars | -| receiverSignatureRequired | bool | optional | | -| autoRenewPeriod | int64 | optional | Units of seconds | -| memo | string | optional | | -| maxAutoTokenAssociations | int32 | optional | | -| stakedAccountId | string | optional | | -| stakedNodeId | int64 | optional | | -| declineStakingReward | bool | optional | | -| alias | string | optional | Hex string representation of the keccak-256 hash of an ECDSAsecp256k1 public key type. | -| signerKey | string | optional | DER-encoded hex string representation of an additional private key required to sign. | +| Parameter Name | Type | Required/Optional | Description/Notes | +|---------------------------|--------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| key | string | optional | DER-encoded hex string representation for private or public keys. Keylists and threshold keys are the hex of the serialized protobuf bytes. | +| initialBalance | int64 | optional | Units of tinybars | +| receiverSignatureRequired | bool | optional | | +| autoRenewPeriod | int64 | optional | Units of seconds | +| memo | string | optional | | +| maxAutoTokenAssociations | int32 | optional | | +| stakedAccountId | string | optional | | +| stakedNodeId | int64 | optional | | +| declineStakingReward | bool | optional | | +| alias | string | optional | Hex string representation of the keccak-256 hash of an ECDSAsecp256k1 public key type. | +| signerKeys | list | optional | List of DER-encoded hex strings of all additional private keys required to sign. | ### Output Parameters @@ -136,11 +136,11 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api - If true, this account's key must sign any transaction depositing into this account (in addition to all withdrawals). -| Test no | Name | Input | Expected response | Implemented (Y/N) | -|---------|--------------------------------------------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------|-------------------| -| 1 | Creates an account that requires a receiving signature | key=, receiverSignatureRequired=true | The account creation succeeds and the account requires a receiving signature. | N | -| 2 | Creates an account that doesn't require a receiving signature | key=, receiverSignatureRequired=false | The account creation succeeds and the account doesn't require a receiving signature. | N | -| 3 | Creates an account that requires a receiving signature but isn't signed by the account key | key=, receiverSignatureRequired=true | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | +| Test no | Name | Input | Expected response | Implemented (Y/N) | +|---------|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|-------------------| +| 1 | Creates an account that requires a receiving signature | key=, receiverSignatureRequired=true, signerKeys=[] | The account creation succeeds and the account requires a receiving signature. | N | +| 2 | Creates an account that doesn't require a receiving signature | key=, receiverSignatureRequired=false | The account creation succeeds and the account doesn't require a receiving signature. | N | +| 3 | Creates an account that requires a receiving signature but isn't signed by the account key | key=, receiverSignatureRequired=true | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | #### JSON Request Example @@ -150,8 +150,11 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api "id": 99232, "method": "createAccount", "params": { - "key": "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d", - "receiverSignatureRequired": true + "key": "302a300506032b6570032100e9a0f9c81b3a2bb81a4af5fe05657aa849a3b9b0705da1fb52f331f42cf4b496", + "receiverSignatureRequired": true, + "signerKeys": [ + "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d" + ] } } ``` @@ -351,14 +354,14 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api } ``` -### **Decline rewards:** +### **Decline Reward:** - If true, the account declines receiving a staking reward. | Test no | Name | Input | Expected response | Implemented (Y/N) | |---------|---------------------------------------------------------|----------------------------------------------|--------------------------------------------------------------------------------|-------------------| | 1 | Creates an account that declines staking rewards | key=, declineStakingRewards=true | The account creation succeeds and the account declines staking rewards. | N | -| 1 | Creates an account that doesn't decline staking rewards | key=, declineStakingRewards=false | The account creation succeeds and the account doesn't decline staking rewards. | N | +| 2 | Creates an account that doesn't decline staking rewards | key=, declineStakingRewards=false | The account creation succeeds and the account doesn't decline staking rewards. | N | #### JSON Request Example @@ -391,11 +394,11 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api - The bytes to be used as the account's alias. The bytes must be formatted as the calculated last 20 bytes of the keccak-256 hash of an ECDSA primitive key. -| Test no | Name | Input | Expected response | Implemented (Y/N) | -|---------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|-------------------| -| 1 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key | key=, alias=, signerKey= | The account creation succeeds and the account has the keccak-256 hash of the ECDSAsecp256k1 public key as its alias. | N | -| 2 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key without a signature | key=, alias= | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | -| 3 | Creates an account with an invalid alias | key=, alias= | The account creation fails with an INVALID_ALIAS_KEY response code from the network. | N | +| Test no | Name | Input | Expected response | Implemented (Y/N) | +|---------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|-------------------| +| 1 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key | key=, alias=, signerKeys=[] | The account creation succeeds and the account has the keccak-256 hash of the ECDSAsecp256k1 public key as its alias. | N | +| 2 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key without a signature | key=, alias= | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | +| 3 | Creates an account with an invalid alias | key=, alias= | The account creation fails with an INVALID_ALIAS_KEY response code from the network. | N | #### JSON Request Example @@ -407,7 +410,9 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api "params": { "key": "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d", "alias": "990a3f6573669cc6266c00983dc24359bd4b223b", - "signerKey": "30540201010420c5f9d140822511e581228feb2bde5a9706ee4c4377822e7cf4755fec529f0bcfa00706052b8104000aa124032200038064ccfe93ce1492ada790da7204edd8e3fd004ee68e4fae7641e00db20527c5" + "signerKeys": [ + "30540201010420c5f9d140822511e581228feb2bde5a9706ee4c4377822e7cf4755fec529f0bcfa00706052b8104000aa124032200038064ccfe93ce1492ada790da7204edd8e3fd004ee68e4fae7641e00db20527c5" + ] } } ``` From 1a10946a7713352a77e4dedfcdd4e80865d75676 Mon Sep 17 00:00:00 2001 From: Rob Walworth Date: Mon, 20 May 2024 10:02:57 -0500 Subject: [PATCH 2/3] docs: tests for receiving signature only require VALID_KEY, not VALID_PRIVATE_KEY or VALID_PUBLIC_KEY Signed-off-by: Rob Walworth --- .../crypto-service/accountCreateTransaction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test-specifications/crypto-service/accountCreateTransaction.md b/test-specifications/crypto-service/accountCreateTransaction.md index a9d7c31..36d1471 100644 --- a/test-specifications/crypto-service/accountCreateTransaction.md +++ b/test-specifications/crypto-service/accountCreateTransaction.md @@ -139,8 +139,8 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api | Test no | Name | Input | Expected response | Implemented (Y/N) | |---------|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|-------------------| | 1 | Creates an account that requires a receiving signature | key=, receiverSignatureRequired=true, signerKeys=[] | The account creation succeeds and the account requires a receiving signature. | N | -| 2 | Creates an account that doesn't require a receiving signature | key=, receiverSignatureRequired=false | The account creation succeeds and the account doesn't require a receiving signature. | N | -| 3 | Creates an account that requires a receiving signature but isn't signed by the account key | key=, receiverSignatureRequired=true | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | +| 2 | Creates an account that doesn't require a receiving signature | key=, receiverSignatureRequired=false | The account creation succeeds and the account doesn't require a receiving signature. | N | +| 3 | Creates an account that requires a receiving signature but isn't signed by the account key | key=, receiverSignatureRequired=true | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | #### JSON Request Example From ed76387477f7fa650bc3dcccd0c2a56fdb5f5ddc Mon Sep 17 00:00:00 2001 From: Rob Walworth Date: Wed, 22 May 2024 13:44:36 -0500 Subject: [PATCH 3/3] docs: create commonTransactionsParameters docs to hold parameters that are common between all transactions Signed-off-by: Rob Walworth --- .../commonTransactionParameters.md | 35 +++++++++++ .../accountCreateTransaction.md | 62 ++++++++++--------- 2 files changed, 68 insertions(+), 29 deletions(-) create mode 100644 test-specifications/commonTransactionParameters.md diff --git a/test-specifications/commonTransactionParameters.md b/test-specifications/commonTransactionParameters.md new file mode 100644 index 0000000..875c79b --- /dev/null +++ b/test-specifications/commonTransactionParameters.md @@ -0,0 +1,35 @@ +# Common Transaction Parameters + +There are common parameters that can be set for all Hedera transaction types. This document specifies a common JSON object that should be added to all transactions that encapsulates these common parameters. + +## Transaction Parameter Object Definition + +| Parameter Name | Type | Required/Optional | Description/Notes | +|--------------------------|--------------|-------------------|----------------------------------------------------------------------------------| +| transactionId | string | optional | | +| maxTransactionFee | int64 | optional | Units of tinybars | +| validTransactionDuration | int64 | optional | Units of seconds | +| memo | string | optional | | +| regenerateTransactionId | bool | optional | | +| signers | list | optional | List of DER-encoded hex strings of all additional private keys required to sign. | + +## Example Usage + +If the `createAccount` method were to contain this object and name it `"commonTransactionParams"`, its usage would look like: + +```json +{ + "jsonrpc": "2.0", + "id": 99232, + "method": "createAccount", + "params": { + "key": "302a300506032b6570032100e9a0f9c81b3a2bb81a4af5fe05657aa849a3b9b0705da1fb52f331f42cf4b496", + "receiverSignatureRequired": true, + "commonTransactionParams": { + "signers": [ + "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d" + ] + } + } +} +``` diff --git a/test-specifications/crypto-service/accountCreateTransaction.md b/test-specifications/crypto-service/accountCreateTransaction.md index 36d1471..86f42cd 100644 --- a/test-specifications/crypto-service/accountCreateTransaction.md +++ b/test-specifications/crypto-service/accountCreateTransaction.md @@ -30,19 +30,19 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api ### Input Parameters -| Parameter Name | Type | Required/Optional | Description/Notes | -|---------------------------|--------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| key | string | optional | DER-encoded hex string representation for private or public keys. Keylists and threshold keys are the hex of the serialized protobuf bytes. | -| initialBalance | int64 | optional | Units of tinybars | -| receiverSignatureRequired | bool | optional | | -| autoRenewPeriod | int64 | optional | Units of seconds | -| memo | string | optional | | -| maxAutoTokenAssociations | int32 | optional | | -| stakedAccountId | string | optional | | -| stakedNodeId | int64 | optional | | -| declineStakingReward | bool | optional | | -| alias | string | optional | Hex string representation of the keccak-256 hash of an ECDSAsecp256k1 public key type. | -| signerKeys | list | optional | List of DER-encoded hex strings of all additional private keys required to sign. | +| Parameter Name | Type | Required/Optional | Description/Notes | +|---------------------------|--------------------------------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| key | string | optional | DER-encoded hex string representation for private or public keys. Keylists and threshold keys are the hex of the serialized protobuf bytes. | +| initialBalance | int64 | optional | Units of tinybars | +| receiverSignatureRequired | bool | optional | | +| autoRenewPeriod | int64 | optional | Units of seconds | +| memo | string | optional | | +| maxAutoTokenAssociations | int32 | optional | | +| stakedAccountId | string | optional | | +| stakedNodeId | int64 | optional | | +| declineStakingReward | bool | optional | | +| alias | string | optional | Hex string representation of the keccak-256 hash of an ECDSAsecp256k1 public key type. | +| commonTransactionParams | [json object](../commonTransactionParameters.md) | optional | | ### Output Parameters @@ -136,11 +136,11 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api - If true, this account's key must sign any transaction depositing into this account (in addition to all withdrawals). -| Test no | Name | Input | Expected response | Implemented (Y/N) | -|---------|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|-------------------| -| 1 | Creates an account that requires a receiving signature | key=, receiverSignatureRequired=true, signerKeys=[] | The account creation succeeds and the account requires a receiving signature. | N | -| 2 | Creates an account that doesn't require a receiving signature | key=, receiverSignatureRequired=false | The account creation succeeds and the account doesn't require a receiving signature. | N | -| 3 | Creates an account that requires a receiving signature but isn't signed by the account key | key=, receiverSignatureRequired=true | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | +| Test no | Name | Input | Expected response | Implemented (Y/N) | +|---------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|-------------------| +| 1 | Creates an account that requires a receiving signature | key=, receiverSignatureRequired=true, commonTransactionParams.signers=[] | The account creation succeeds and the account requires a receiving signature. | N | +| 2 | Creates an account that doesn't require a receiving signature | key=, receiverSignatureRequired=false | The account creation succeeds and the account doesn't require a receiving signature. | N | +| 3 | Creates an account that requires a receiving signature but isn't signed by the account key | key=, receiverSignatureRequired=true | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | #### JSON Request Example @@ -152,9 +152,11 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api "params": { "key": "302a300506032b6570032100e9a0f9c81b3a2bb81a4af5fe05657aa849a3b9b0705da1fb52f331f42cf4b496", "receiverSignatureRequired": true, - "signerKeys": [ - "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d" - ] + "commonTransactionParams": { + "signers": [ + "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d" + ] + } } } ``` @@ -394,11 +396,11 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api - The bytes to be used as the account's alias. The bytes must be formatted as the calculated last 20 bytes of the keccak-256 hash of an ECDSA primitive key. -| Test no | Name | Input | Expected response | Implemented (Y/N) | -|---------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|-------------------| -| 1 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key | key=, alias=, signerKeys=[] | The account creation succeeds and the account has the keccak-256 hash of the ECDSAsecp256k1 public key as its alias. | N | -| 2 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key without a signature | key=, alias= | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | -| 3 | Creates an account with an invalid alias | key=, alias= | The account creation fails with an INVALID_ALIAS_KEY response code from the network. | N | +| Test no | Name | Input | Expected response | Implemented (Y/N) | +|---------|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|-------------------| +| 1 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key | key=, alias=, commonTransactionParams.signers=[] | The account creation succeeds and the account has the keccak-256 hash of the ECDSAsecp256k1 public key as its alias. | N | +| 2 | Creates an account with the keccak-256 hash of an ECDSAsecp256k1 public key without a signature | key=, alias= | The account creation fails with an INVALID_SIGNATURE response code from the network. | N | +| 3 | Creates an account with an invalid alias | key=, alias= | The account creation fails with an INVALID_ALIAS_KEY response code from the network. | N | #### JSON Request Example @@ -410,9 +412,11 @@ https://docs.hedera.com/hedera/sdks-and-apis/rest-api "params": { "key": "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d", "alias": "990a3f6573669cc6266c00983dc24359bd4b223b", - "signerKeys": [ - "30540201010420c5f9d140822511e581228feb2bde5a9706ee4c4377822e7cf4755fec529f0bcfa00706052b8104000aa124032200038064ccfe93ce1492ada790da7204edd8e3fd004ee68e4fae7641e00db20527c5" - ] + "commonTransactionParams": { + "signers": [ + "30540201010420c5f9d140822511e581228feb2bde5a9706ee4c4377822e7cf4755fec529f0bcfa00706052b8104000aa124032200038064ccfe93ce1492ada790da7204edd8e3fd004ee68e4fae7641e00db20527c5" + ] + } } } ```