Association

Create an association between account. An association can represent any kind of relationship. The meaning is defined by the association type.

JSON

{
  "type": 16,
  "version": 4,
  "id": "7xzhQ5dkehS547ejG4X17QRBvJigT7ruELgLp7qff6G9",
  "sender": "3NBcx7AQqDopBj3WfwCVARNYuZyt1L9xEVM",
  "senderKeyType": "ed25519",
  "senderPublicKey": "7gghhSwKRvshZwwh6sG97mzo1qoFtHEQK7iM4vGcnEt7",
  "fee": 60000000,
  "timestamp": 1689090586785,
  "associationType": 1,
  "recipient": "3N2XoMuukk4BPiLn95vDkv4ocU5szMXuxVN",
  "expires": 1704067200000,
  "subject": "3yZe7d",
  "data": [
    {
      "key": "str",
      "type": "string",
      "value": "some text"
    },
    {
      "key": "int",
      "type": "integer",
      "value": 1234567
    },
    {
      "key": "bool",
      "type": "boolean",
      "value": true
    },
    {
      "key": "bin",
      "type": "binary",
      "value": "base64:aGVsbG8="
    }
  ],
  "proofs": [
    "2k6hCWSQdJhMkSni4q6Y76X1obGCx2B3FPEsJXtJLyG3aaJAYeCNMAmGhdTqHxzM7m4SKLgJ7iV8UFF2Dmq5jAJa"
  ],
  "height": 2546397,
  "effectiveFee": 49587000
}

• id and height should be omitted when broadcasting. These fields are set by the node.

• subject is optional.

• Binary strings are base58 encoded.

• timestamp and expires is in microseconds since epoch.

• fee includes 8 digits, so LTO * 10^8

Associations that are recently expired may still be returned by the node. The public node will use the time of the last mined block to determine if an association is expired or not.

Association identifier

An association is identified by the sender, recipient, association type, and subject. With this information, the association can be revoked.

Submitting a new association transaction with the same sender, recipient, association type, and subject will overwrite the expiry date and data.

Since the subject is part of the identifier, it's not possible to change the subject of an existing association.

Data entries

Since version 4, association transactions can have data entries. These are similar to those of the data transaction.

Binary schema

The binary data structure of the unsigned transaction.

V4 (current)

#	Field Name	Type	Length
1	Transaction type	Byte (constant, value=16)	1
2	Version	Byte (constant, value=3)	1
3	Network id	Byte	1
4	Timestamp	Long	8
5	Sender's key type	KeyType (Byte)	1
6	Sender's public key	PublicKey (Array[Byte])	32 | 33
7	Fee	Long	8
8	Recipient	Address (Array[Byte])	26
9	Association type	Int	4
10	Expires	Long	8
11	Subject length (N)	Short	2
12	Subject	Array[Byte]	N
13	Number of entries	Short	2
14	Entry 1
...

• If the association doesn't expire, the expiry timestamp in the binary data must be zero.

• Network id can be obtained by taking the 2nd byte from the sender address.

• Each key type has a numeric id in addition to the reference from the JSON.

• Integers (short, int, long) have a big endian byte order.

V3

#	Field Name	Type	Length
1	Transaction type	Byte (constant, value=16)	1
2	Version	Byte (constant, value=3)	1
3	Network id	Byte	1
4	Timestamp	Long	8
5	Sender's key type	KeyType (Byte)	1
6	Sender's public key	PublicKey (Array[Byte])	32 | 33
7	Fee	Long	8
8	Recipient	Address (Array[Byte])	26
9	Association type	Int	4
10	Expires	Long	8
11	Subject length (N)	Short	2
12	Subject	Array[Byte]	N

• If the association doesn't expire, the expiry timestamp in the binary data must be zero.

• Network id can be obtained by taking the 2nd byte from the sender address.

• Each key type has a numeric id in addition to the reference from the JSON.

• Integers (short, int, long) have a big endian byte order.

V1

#	Field Name	Type	Length
1	Transaction type	Byte (constant, value=16)	1
2	Version	Byte (constant, value=1)	1
3	Chain id	Byte	1
4	Sender's public key	PublicKey (Array[Byte])	32
5	Party	Address (Array[Byte])	26
6	Association type	Int	4
7	Includes subject	Boolean (Byte)	1
8	Subject length (N)	Short	2
9	Subject	Array[Byte]	N
10	Timestamp	Long	8
11	Fee	Long	8

If the association doesn't include a hash, the hash length and hash should be omitted from the binary data.

• Chain id can be obtained by taking the 2nd byte from the sender or recipient address.

• Integers (short, int, long) have a big endian byte order.

The encoding of a data entry depends on the type. For more information see "Binary schema of data entries".