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.

Sign up for GitHub

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

Jump to bottom

docs: Add test specifications for TokenAssociateTransaction #264

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Add test specifications for TokenAssociateTransaction #264

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
142 changes: 142 additions & 0 deletions test-specifications/token-service/tokenAssociateTransaction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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<string> | 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. <CREATED_ACCOUNT_ID> will denote the ID of the account, and <CREATED_ACCOUNT_PRIVATE_KEY> 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=<OPERATOR_ACCOUNT_ID>, and tokenType="ft". <CREATED_TOKEN_ID> 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=<CREATED_ACCOUNT_ID>, tokenIds=[<CREATED_TOKEN_ID>], commonTransactionParams.signers=[<CREATED_ACCOUNT_PRIVATE_KEY>] | The token association succeeds and the token is associated with <CREATED_ACCOUNT_ID>. | N |
| 2 | Associates a token with an account with which it is already associated | accountId=<CREATED_ACCOUNT_ID>, tokenIds=[<CREATED_TOKEN_ID>], commonTransactionParams.signers=[<CREATED_ACCOUNT_PRIVATE_KEY>] | 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=<CREATED_ACCOUNT_ID>, tokenIds=[<CREATED_TOKEN_ID>] | 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=[<CREATED_TOKEN_ID>] | 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=<DELETED_ACCOUNT_ID>, tokenIds=[<CREATED_TOKEN_ID>], commonTransactionParams.signers=[<DELETED_ACCOUNT_PRIVATE_KEY>] | 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=[<CREATED_TOKEN_ID>] | 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=<CREATED_ACCOUNT_ID>, commonTransactionParams.signers=[<CREATED_ACCOUNT_PRIVATE_KEY>] | The token association succeeds and no associations are made. | N |
| 2 | Associates a token that doesn't exist with an account | accountId=<CREATED_ACCOUNT_ID>, tokenIds=["123.456.789"], commonTransactionParams.signers=[<CREATED_ACCOUNT_PRIVATE_KEY>] | 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=<CREATED_ACCOUNT_ID>, tokenIds=[<DELETED_TOKEN_ID>], commonTransactionParams.signers=[<CREATED_ACCOUNT_PRIVATE_KEY>] | 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=<CREATED_ACCOUNT_ID>, tokenIds=[""], commonTransactionParams.signers=[<CREATED_ACCOUNT_PRIVATE_KEY>] | The token association fails with an SDK internal error. | N |
| 5 | Associates a token twice with an account | accountId=<CREATED_ACCOUNT_ID>, tokenIds=[<CREATED_TOKEN_ID>, <CREATED_TOKEN_ID>], commonTransactionParams.signers=[<CREATED_ACCOUNT_PRIVATE_KEY>] | The token association fails with an TOKEN_ID_REPEATED_IN_TOKEN_LIST response code from the network. | N |
Comment on lines +104 to +108
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be reasonable to add cases here for multiple tokens in a single transaction?
It is supposed to be possible to associate several tokens at a time, and it might be worth testing scenarios including, for example
3 valid tokens
2 valid tokens and one invalid token
3 tokens, two of which are the same ID
3 tokens, one of which is deleted.

I don't actually know the results for those scenarios (e.g. will the system associate the valid tokens, even if the list contains an invalid token, or will the entire transaction be rejected?); which suggests that testing them might be valuable.


#### 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"
}
}
```