Usually, transactions provide transfer of tokens between two addresses. But transactions in the Cellframe network are way more functional. Transactions can be written or not written to the [[Ledger]]. A transaction that is not written to the ledger is called an unconfirmed transaction and is stored in [[Mempool]], a transaction written in the ledger is called confirmed and is stored in [[Chain|chains]]. Accordingly to Cellframe SDK, transaction is a [[Data element (Datum)|datum]] **`DATUM_TX`** which contains a set of items defining its purpose and abilities. ## Structure Transaction consists of a **`HEADER`** and set of attached **`ITEMS`**. Header contains information about transactions status, hash, ticker of the token being used, error code (number and string) in case of any errors occurred, and of course, timestamp of creation. ```bash status - status of transaction (pending, accepted, declined) hash - hash in the HEX format token_ticker - the name of the token which is used in transaction ret_code - error code (in case something went wrong) ret_code_str - error message (in case something went wrong) tx_created - timestamp of creation ``` Let's consider its structure in the example below. **`HEADER:`** ```bash status: ACCEPTED hash: 0x837B23DF0C01110E25BDF80AB346E28F0A8C03151B759DC971399A27206399E2 ret_code: 0 ret_code_str: No error action: regular batching: false first transaction: tx created: Mon, 17 Feb 2025 03:38:56 +0700 token ticker: CELL ``` **`FIELDS:`** **`status:`** status of transaction in the ledger (`ACCEPTED` or `DECLINED`) **`hash:`** hash of the transaction in the HEX format **`ret_code:`** code of error (`0` if everything is ok) **`ret_code_str:`** string value of error code (`no error` if everything is ok) **`action:`** type of action (list of actions is presented below) **`batching:`** `true`, if transaction was used to transfer funds on multiple wallets, `false` otherwise **`first transaction:`** hash of the original transaction **`tx_created:`** timestamp of transaction creation in the RFC822 format **`token_ticker:`** name of the token **`ACTIONS:`** ```actionscript TRANSFER_REGULAR TRANSFER_COMISSION TRANSFER_CROSSCHAIN TRANSFER_REWARD OPEN USE EXTEND CHANGE CLOSE VOTING VOTE ``` Despite header, this transaction also has 5 attached items: **`IN`**, **`OUT(1)`**, **`OUT COND` -`DAP_CHAIN_TX_OUT_COND_SUBTYPE_FEE(2)`**, **`OUT(3)`** and **`SIG`**. **`ITEMS:`** ```bash item type: IN Tx prev hash: 0x5D72AF540B571F87839F9433A9FE0D7E92F84946C2B3528969D6191E28AFE150 Tx out prev idx: 2 `` item type: OUT Coins: 0.00001 Value: 10000000000000 Address: Rj7J7MiX2bWy8sNyXJ7RMzDBPmMNkixv26WCaLBWuN1R7X9nDqFuqW1B2BnupQVwm71fmexnx84gYdCbsFTNptTpyi9rVgmsnfHBw7h5 item type: OUT COND ts_expires: never coins: 0.00001 value: 10000000000000 subtype: DAP_CHAIN_TX_OUT_COND_SUBTYPE_FEE uid: 0x0000000000000000 tsd_size: 0 item type: OUT Coins: 0.00956 Value: 9560000000000000 Address: Rj7J7MiX2bWy8sNyWeBT5vNT8hH2kBWdmULxaVQ298X11tsizypMQM2FSad7MH4ZGxS6vFPz7aMkftc6n2H7egqWvdsfBwmkuXEc4APy item type: SIG Signature: Type: sig_dil Public key hash: 0x02FFC8763A20F8C3CD3D4D73B2B1A2F73E33764900EA94A2E9FFA52D68D8AC77 Public key size: 1196 Signature size: 2096 Sender addr: Rj7J7MiX2bWy8sNyWeBT5vNT8hH2kBWdmULxaVQ298X11tsizypMQM2FSad7MH4ZGxS6vFPz7aMkftc6n2H7egqWvdsfBwmkuXEc4APy ``` ## Items Every item is prepended with one byte item type ID, so on start we have not more than 255 types of items. Here are some that already present in the code: - **[[5. Transactions Structure#Input|Input]]** - **[[5. Transactions Structure#Conditional Input|Conditional Input]]** - **[[5. Transactions Structure#Output|Output]]** - **[[5. Transactions Structure#1. Fee|Conditional Out - Fee]]** - **[[5. Transactions Structure#2. Service Payment|Conditional Out - Service Payment]]** - **[[5. Transactions Structure#3. Exchange Service|Conditional Out - Exchange Service]]** - **[[5. Transactions Structure#4. Staking Service|Conditional Out - Staking Service]]** - **[[5. Transactions Structure#5. Delegated Staking Service|Conditional Out - Delegated Staking Service]]** - **[[5. Transactions Structure#Voting|Voting]]** - **[[5. Transactions Structure#Vote|Vote]]** - **[[5. Transactions Structure#Signature|Signature]]** - **[[5. Transactions Structure#Receipt|Receipt]]** - **[[5. Transactions Structure#TSD Section|TSD Section]]** > [!NOTE] Note > Item fields are described in this way: > **`field name`**: field description: `data type` ### Input This item serves as a funds entering point into the transaction. The regular **input** can receive funds from the [[3. JSON Format of Transactions#Output|output]] of another previous transaction. For this **`Tx out prev idx`** and **`Tx prev hash`** of the target transaction must be specified. **`FIELDS:`** **`item type:`** type of the item - **`IN`**: `string` **`Tx prev hash:`** hash of previous transaction: `string` **`Tx out prev idx:`** ID of the target output; ID is the serial number of **`OUT`** in the transaction starting with **`0`**: `uint64` **`EXAMPLE:`** ```json item type: IN Tx prev hash: 0x5D72AF540B571F87839F9433A9FE0D7E92F84946C2B3528969D6191E28AFE150 Tx out prev idx: 2 ``` ### Conditional Input This item is like regular **[[3. JSON Format of Transactions#Input|input]]** prescribed to receive incoming funds from the previous transaction, but **[[3. JSON Format of Transactions#Conditional Input|conditional input]]** can receive funds only from the **[[3. JSON Format of Transactions#Conditional Outputs|conditional outputs]]**. The fields are quite the same, but in case of service payment, there also must be specified **`Receipt_idx`** of the **[[Receipt|receipt]]** from the target transaction. **`FIELDS:`** **`item type:`** type of the item - **`IN COND`**: `string` **`Receipt_idx:`** ID of the receipt; optional field: **`int`** **`Tx_prev_hash:`** hash of the target previous transaction: `string` **`Tx_out_prev_idx:`** ID of the target output; ID is the serial number of **`OUT`** in the transaction starting with **`0`**: `uint64` **`EXAMPLE:`** ```json item type: IN COND Receipt_idx: 0 Tx_prev_hash: 0xAEF5F6D254387F7798BF50F176B2112ED60ABF53396D896B00A3333DC22626E9 Tx_out_prev_idx: 0 ``` ### Output The output item serves as an exit for funds from the transaction. Usually, funds are taken to Output from the Input or Conditional Input of the same transaction. But funds can be taken also from the INPUT EMISSION item. To transfer funds from the output, it is mandatory to specify **`Addr`** of the receiving wallet, **`Token`** ticker and **`Value`** of funds being transferred. **`FIELDS:`** **`item type:`** type of the item - **`OUT`**: `string` **`Addr:`** wallet address of the receiver: `string` **`Token:`** name of the token: `string` **`Coins:`** amount of funds being transferred in coins: `string` **`Value:`** amount of funds being transferred: `string` **`EXAMPLE:`** ```json item type: OUT Addr: Rj7J7MiX2bWy8sNyWeQS3iBok3hGXuxni6Tg71GVBnjBkrvrZcrK24m7vF5CLQxprQdBchXrnUJR9hDu5SzGFU7JP4nRVnBikHsjGHph Token: CELL Coins: 4.691284117214960025 Value: 4691284117214960025 ``` ### Conditional Outputs These items are created to provide payments, exchanges, stakes and many more. These outputs differ from regular output with a special condition, which is being fulfilled to acquire funds. #### 1. Fee This item is used to pay for validator services. Once the validator approves the transaction, funds from the conditional **`FEE`**  output of this transaction can be transferred to his wallet. Almost every transaction includes this item, with very rare exceptions. The recommended validator fee amount can be found **[[fee|here]]**. **`FIELDS:`** **`item type:`** type of the item - **`OUT COND`**: `string` **`ts_expires:`** timestamp of expiration specified in RFC822 format, if not specified, **`never`** is used by default: `string` **`coins:`** fee size calculated in coins: `string` **`value:`** fee size: `string` **`subtype:`** subtype of the **`COND OUT`** item - **`FEE`**: `string` **`uid:`** unique ID of the service, **`0x0000000000000000`** by default: `string` **`tsd_size:`** size of the applied TSD sections: `int` **`EXAMPLE:`** ```json item type: OUT COND ts_expires: never coins: 0.05 value: 50000000000000000 subtype: DAP_CHAIN_TX_OUT_COND_SUBTYPE_FEE uid: 0x0000000000000000 tsd_size: 0 ``` #### 2. Service Payment An item designed for services payment in Cellframe networks. To pay for the use of a service, you need to specify the fee **`value`**, the kind of a unit **`unit`** (megabytes or seconds), the maximal cost per one unit **`max price (value)`**, as well as the provider's public key **`pkey`** indicated in the [[3. JSON Format of Transactions#Receipt|receipt]]. If the provider's public key matches the public key specified in the receipt, the provider will be able to withdraw funds from this conditional **`SRV_PAY`** output. **`FIELDS:`** **`item type:`** type of the item - **`OUT COND`**: `string` **`ts_expires:`** timestamp of expiration specified in RFC822 format, if not specified, **`never`** is used by default: `string` **`coins:`** payment sum calculated in coins: `string` **`value:`** payment sum: `string` **`subtype:`** subtype of the **`OUT COND`** item - **`SRV_PAY`**: `string` **`uid:`** ID of the service, **`0x0000000000000001`** by default: `string` **`tsd_size:`** size of the applied TSD sections: `int` **`unit:`** kind of service unit, **`seconds`** or **`megabytes`**: `string` **`pkey:`** public key of service-provider: `string` **`max price (coins):`** maximal price for one unit in coins: `string` **`max price (value):`** maximal price for one unit: `string` **`EXAMPLE:`** ```json item type: OUT COND ts_expires: never coins: 0.06 value: 60000000000000000 subtype: DAP_CHAIN_TX_OUT_COND_SUBTYPE_SRV_PAY uid: 0x0000000000000001 tsd_size: 0 unit: 0x00000002 pkey: 0x3E6079BA2AC5F73836BB15A64D8BAF597A0EB0931054BDEEE760E5B0673EFD6A max price(coins): 0.0 max price(value): 0 ``` #### 3. Exchange Service This item is designed for operations on the Cellframe **[[Decentralized Exchange Service (DEX)]]**. It allows users to exchange tokens **`buy_token`** at specified **`rate`** between users within a specific network **`net id`**. **`FIELDS:`** **`item type:`** type of the item - **`OUT COND`**: `string` **`ts_expires:`** timestamp of expiration specified in RFC822 format, if not specified, **`never`** is used by default: `string` **`coins:`** sum of tokens being exchanged in coins: `string` **`value:`** sum of tokens being exchanged: `string` **`subtype:`** subtype of the **`OUT COND`** item - **`SRV_XCHANGE`**: `string` **`uid:`** ID of the service, **`0x2`** by default: `string` **`tsd_size:`** size of the applied TSD sections: `int` **`net id:`** ID of the network where order is placed: `string` **`buy_token:`** ticker of token being bought: `string` **`rate:`** exchange rate calculated this way "token_buy/token_sell": `string` `Network ID's in the Cellframe:` ```actionscript Backbone - id=0x0404202200000000 KelVPN - id=0x1807202300000000 mileena - id=0x000000000000cccc raiden - id=0x000000000000bbbb riemann - id=0x000000000000dddd subzero - id=0x000000000000acca ``` **`EXAMPLE:`** ```json item type: OUT COND ts_expires: never coins: 1.0 value: 1000000000000000000 subtype: DAP_CHAIN_TX_OUT_COND_SUBTYPE_SRV_XCHANGE uid: 0x0000000000000002 tsd_size: 0 net id: 0x000000000000dddd buy_token: mtKEL rate: 1.0 ``` #### 4. Staking Service An item created for the **[[Stake|staking service]]**, specifically designed to lock a certain amount of funds **`value`** in a specified conditional output for a defined period of time **`time_unlock`**. **`FIELDS:`** **`item type:`** type of the item - **`OUT COND`**: `string` **`ts_expires:`** timestamp of expiration specified in RFC822 format, if not specified, **`never`** is used by default: `string` **`coins:`** amount of funds to lock in coins: `string` **`value:`** amount of funds to lock: `string` **`subtype:`** subtype of the **`OUT COND`** item - **`SRV_STAKE_LOCK`**: `string` **`uid:`** ID of the service, `0x12` by default: `string` **`time_unlock:`** timestamp in RFC822 format that specifies when the funds will be unlocked: `string` **`EXAMPLE:`** ```json item type: OUT COND Header: ts_expires: never coins: 81.0 value: 81000000000000000000 subtype: DAP_CHAIN_TX_OUT_COND_SUBTYPE_SRV_STAKE_LOCK uid: 0x0000000000000012 time_unlock: Fri, 06 Mar 2026 04:00:01 +0700 ``` #### 5. Delegated Staking Service This item is involved in the operation of the **[[Delegated Stakes|delegated staking]]** service. With its help, you can delegate your "consensus weight" to another node **`signer_node_addr`**, meaning that your **[[Token Delegated (m-token)|m-tokens]]** from the address **`signing_addr`** in the amount of **`value`** will contribute to the total weight of the specified node. **`FIELDS:`** **`item type:`** type of the item - **`COND OUT`**: `string` **`ts_expires:`** timestamp of expiration specified in RFC822 format, if not specified, `never` is used by default: `string` **`coins:`** amount of funds being delegated in coins: `string` **`value:`** amount of funds being delegated: `string` **`subtype:`** subtype of the **`COND OUT`** item - **`SRV_STAKE_POS_DELEGATE`**: `string` **`uid:`** ID of the service, **`0x13`** by default: `string` **`tsd_size:`** size of the applied TSD sections: `int` **`signing_addr:`** wallet address of the staker: `string` **`with pkey hash:`** public key hash of the of the signing address: `string` **`signer_node_addr:`** node address of the target validator: `string` **`EXAMPLE:`** ```json item type: OUT COND ts_expires: never coins: 10.1 value: 10100000000000000000 subtype: DAP_CHAIN_TX_OUT_COND_SUBTYPE_SRV_STAKE_POS_DELEGATE uid: 0x0000000000000013 tsd_size: 0 signing_addr: o9z3wUTSTicckJuozhPr6oMEAtya7JnStmo8UvkBJ9TcHc9ooUPksbmAEWSrgt9tzNRbop3XGniUJuXRWGQUbNujR4ugg1WZ3L8s9K7F with pkey hash: 0xC51165F05F83FDF16D682658927B65F90F930E147D31AE15662842F174538F25 signer_node_addr: 4A34::01E2::FE8C::C0B4 ``` ### Voting To create a **[[2. Transactions Functions#Voting service|poll transaction]]**, this item is required. The user who wants to initiate a poll must specify the question **`Voting question`** and the answer options **`Answer options`**. The maximum number of votes **`Votes max count`** and the voting expiration time **`Voting expire`** are optional parameters. Additionally, options such as allowing participants to change their answer **`Changing vote is`** and the presence of a delegated key for participating in the vote **`Delegated key for participating in voting`** can be added. **`FIELDS:`** **`item type:`** type of the item - **`VOTING`**: `string` **`Voting question:`** question which was put to a vote: `string` **`Answer options:`** available answers: `string` **`Changing vote is:`** ability to change answer after voting: **`available`/ `not available`**; optional field: `string` **`Delegated key for participating in voting:`** necessity of delegated key for voting: **`required`/ `not required`**; optional field: `string` **`Voting expire:`** timestamp of poll expiration in RFC822 format; optional field: `string` **`Votes max count:`** manimal votes quantity; optional field: `uint64` **`EXAMPLE:`** ```json item type: VOTING Voting question: Do you like cellframe? Answer options: 0: Yes 1: No Changing vote is: not available Delegated key for participating in voting: not required ``` ### Vote This item is used to participate in an already created poll. To vote, the user must specify in which voting **`Voting hash`** he wants to participate and select an answer option **`Vote answer idx`**. **`FIELDS:`** **`item type:`** type of the item - **`VOTE`**: `string` **`Voting hash:`** hash of the poll: `string` **`Vote answer idx:`** ID of the answer option: `uint64` **`EXAMPLE:`** ```json item type: VOTE Voting hash: 0xD14C2A64BE7C5887FC57C9D605F99983869D78F2AE39EF8664B529AD207A00C1 Vote answer idx: 0 ``` ### Signature The signature is stored in this item. It contains a public key hash **`Public key hash`** in BASE64 format and its size. **`FIELDS:`** **`item type:`** type of the item - **`SIG`**: `string` **`Type:`** type of the signature, for example **`sig_dil`**: `string` **`Public key hash:`** public hash of the signature in BASE64 format: `string` **`Public key size:`** size of the public key hash in bytes: `uint64` **`Signature size:`** size of the signature in bytes: `uint64` **`Sender addr:`** wallet address of the signer: `string` **`EXAMPLE:`** ```json item type: SIG Signature: Type: sig_dil Public key hash: 0x934FDFC4DDE770F5E4C2D42976713F64D680A20F4685A1BEB5A4AAA4B87904B6 Public key size: 1196 Signature size: 2096 Sender addr: Rj7J7MiX2bWy8sNyZXXX6dmBSNnLgdiW5mL2caVisfHVu5BheM3sk4VLXZ8dfwwBrjbBL22nX8sUpJN1pEwD1hkrTQ5SB36gXy5do155 ``` ### Receipt This item is used to issue a **[[3. JSON Format of Transactions#Receipt|receipt]]** for payment. The service provider specifies here the ID of the provided service **`uid`**, the unit of service **`units type`** (seconds or megabytes), the number of provided **`units`** and the total cost **`value`**. **`FIELDS:`** **`item type:`** type of the item - **`RECEIPT`**: `string` **`size:`** size of the datum: `uint64` **`ext size:`** size of the extended datum elements: `uint64` **`units:`** quantity of provided service units: `uint64` **`uid:`** ID of the provided service: `string` **`units type:`** kind of service unit, **`seconds`** or **`megabytes`**: `string` **`coins:`** total receipt sum in coins: `string` **`value:`** total receipt sum: `string` **`EXAMPLE:`** ```json item type: RECEIPT size: 6693 ext size: 0 INFO: units: 600 uid: 1 units type: SEC coins: 0.05 value: 50000000000000000 Exts: ``` ### TSD Section This item stores the TSD section. Such a section is needed to add some data to a transaction. **`FIELDS:`** **`item type:`** - type of the item - **`TSD data`**: `string` **`type:`** - type of the TSD section: `string` **`size:`** - size of the item in bytes: `uint64` **`EXAMPLE:`** ```json item type: TSD data type: 128 size: 12 ```