diff --git a/test-specifications/token-service/tokenAssociateTransaction.md b/test-specifications/token-service/tokenAssociateTransaction.md new file mode 100644 index 0000000..c88e714 --- /dev/null +++ b/test-specifications/token-service/tokenAssociateTransaction.md @@ -0,0 +1,142 @@ +# TokenAssociateTransaction - Test specification + +## Description: +This test specification for TokenAssociateTransaction is to be one of many for testing the functionality of the Hedera SDKs. The SDK under test will use the language specific JSON-RPC server return responses back to the test driver. + +## Design: +Each test within the test specification is linked to one of the properties within TokenAssociateTransaction. Each property is tested with a mix of boundaries. The inputs for each test are a range of valid, minimum, maximum, negative and invalid values for the method. The expected response of a passed test can be a correct error response code or seen as the result of node queries. A successful transaction (the transaction reached consensus and was applied to state) can be determined by getting a `TransactionReceipt` or `TransactionRecord`, or can be determined by using queries such as `TokenInfoQuery` or `TokenBalanceQuery` and investigating for the required changes (creations, updates, etc.). The mirror node can also be used to determine if a transaction was successful via its rest API. Error codes are obtained from the response code proto files. + +**Transaction properties:** + +https://docs.hedera.com/hedera/sdks-and-apis/sdks/token-service/associate-tokens-to-an-account + +**TokenAssociate protobufs:** + +https://github.com/hashgraph/hedera-protobufs/blob/main/services/token_associate.proto + +**Response codes:** + +https://github.com/hashgraph/hedera-protobufs/blob/main/services/response_code.proto + +**Mirror Node APIs:** + +https://docs.hedera.com/hedera/sdks-and-apis/rest-api + +## JSON-RPC API Endpoint Documentation + +### Method Name + +`associateToken` + +### Input Parameters + +| Parameter Name | Type | Required/Optional | Description/Notes | +|-------------------------|--------------------------------------------------|-------------------|--------------------------------------------------------| +| accountId | string | optional | The ID of the account with which to associate a token. | +| tokenIds | list | optional | The IDs of the tokens to associate. | +| commonTransactionParams | [json object](../commonTransactionParameters.md) | optional | | + +### Output Parameters + +| Parameter Name | Type | Description/Notes | +|----------------|--------|----------------------------------------------------------------------------------------| +| status | string | The status of the submitted `TokenAssociateTransaction` (from a `TransactionReceipt`). | + +### Additional Notes + +The tests contained in this specification will assume that a valid account and a valid token were already successfully created. will denote the ID of the account, and will denote the private key of the account as a DER-encoded hex string. The token shall be created with default values name="testname", symbol="testsymbol", treasuryAccountId=, and tokenType="ft". will denote the ID of the created token. The account will only need to be created once, but a new token should be created for each test. + +## Property Tests + +### **Account ID:** + +- The ID of the account with which to associate a token. + +| Test no | Name | Input | Expected response | Implemented (Y/N) | +|---------|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-------------------| +| 1 | Associates a token with an account | accountId=, tokenIds=[], commonTransactionParams.signers=[] | The token association succeeds and the token is associated with . | N | +| 2 | Associates a token with an account with which it is already associated | accountId=, tokenIds=[], commonTransactionParams.signers=[] | The token association fails with an TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT response code from the network. | N | +| 3 | Associates a token with an account without signing with the account's private key | accountId=, tokenIds=[] | The token association fails with an INVALID_SIGNATURE response code from the network. | N | +| 4 | Associates a token with an account that doesn't exist | accountId="123.456.789", tokenIds=[] | The token association fails with an INVALID_ACCOUNT_ID response code from the network. | N | +| 5 | Associates a token with an account that is deleted | accountId=, tokenIds=[], commonTransactionParams.signers=[] | The token association fails with an INVALID_ACCOUNT_ID response code from the network. | N | +| 6 | Associates a token with an empty account | accountId="", tokenIds=[] | The token association fails with an SDK internal error. | N | + +#### JSON Request Example + +```json +{ + "jsonrpc": "2.0", + "id": 99232, + "method": "associateToken", + "params": { + "accountId": "0.0.2533", + "tokenIds": [ + "0.0.579680", + "0.0.90649" + ], + "commonTransactionParams": { + "signers": [ + "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d" + ] + } + } +} +``` + +#### JSON Response Example + +```json +{ + "jsonrpc": "2.0", + "id": 99232, + "result": { + "status": "SUCCESS" + } +} +``` + +### **Token IDs:** + +- The IDs of the tokens to associate. + +| Test no | Name | Input | Expected response | Implemented (Y/N) | +|---------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-------------------| +| 1 | Associates no tokens with an account | accountId=, commonTransactionParams.signers=[] | The token association succeeds and no associations are made. | N | +| 2 | Associates a token that doesn't exist with an account | accountId=, tokenIds=["123.456.789"], commonTransactionParams.signers=[] | The token association fails with an INVALID_TOKEN_ID response code from the network. | N | +| 3 | Associates a token that is deleted with an account | accountId=, tokenIds=[], commonTransactionParams.signers=[] | The token association fails with an TOKEN_WAS_DELETED response code from the network. | N | +| 4 | Associates a token that is empty with an account | accountId=, tokenIds=[""], commonTransactionParams.signers=[] | The token association fails with an SDK internal error. | N | +| 5 | Associates a token twice with an account | accountId=, tokenIds=[, ], commonTransactionParams.signers=[] | The token association fails with an TOKEN_ID_REPEATED_IN_TOKEN_LIST response code from the network. | N | + +#### JSON Request Example + +```json +{ + "jsonrpc": "2.0", + "id": 99232, + "method": "associateToken", + "params": { + "accountId": "0.0.2533", + "tokenIds": [ + "0.0.579680", + "0.0.90649" + ], + "commonTransactionParams": { + "signers": [ + "302e020100300506032b65700422042031f8eb3e77a04ebe599c51570976053009e619414f26bdd39676a5d3b2782a1d" + ] + } + } +} +``` + +#### JSON Response Example + +```json +{ + "jsonrpc": "2.0", + "id": 99232, + "result": { + "status": "SUCCESS" + } +} +```