Cellframe Wiki

Search

SearchSearch

5. Transactions Structure

Apr 22, 202511 min read

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 chains.

Accordingly to Cellframe SDK, transaction is a 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.

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:

  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:

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:

                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:

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 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:

  item type: IN
                Tx prev hash: 0x5D72AF540B571F87839F9433A9FE0D7E92F84946C2B3528969D6191E28AFE150
                Tx out prev idx: 2

Conditional Input

This item is like regular input prescribed to receive incoming funds from the previous transaction, but conditional input can receive funds only from the conditional outputs. The fields are quite the same, but in case of service payment, there also must be specified Receipt_idx of the 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:

  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:

                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 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:

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 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:

 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:

Backbone - id=0x0404202200000000
KelVPN - id=0x1807202300000000
mileena - id=0x000000000000cccc
raiden - id=0x000000000000bbbb
riemann - id=0x000000000000dddd
subzero - id=0x000000000000acca

EXAMPLE:

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 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:

 
 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 staking service. With its help, you can delegate your “consensus weight” to another node signer_node_addr, meaning that your 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:

 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 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:

  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:

 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:

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 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:

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:

  item type: TSD data
                type: 128
                size: 12

Graph View

Backlinks