transactions.md

Spacemesh 0.2 Transactions

Glossary

• ED22519 - ed25519 signature scheme. Ed25519 is the EdDSA signature scheme using SHA-512 (SHA-2) and Curve25519.
• Ed25519++ - custom ed25519 signature scheme, as implemented in this library. When used, transaction does not include a public key field as the public key can be extracted from the signature.
• NetworkId - 32 byte unique identifier of a particular Spacemesh network, e.g., a testnet or a mainnet. The network id is computed by a full node based on immutable network params and genesis data.
• Address - a Spacemesh address identifies an account. It is the 20-byte suffix of an account's public key.
• XDR - Transactions data is encoded in binary format using the XDR codec.

Supported Transactions Types

Spacemesh 0.2 supports three distinct types of transaction:

1. Simple Coin Transfer Transaction (to another account or app).
2. Call App Transaction - call a method on a smart wallet instance (app).
3. Spawn App Transaction - create a smart wallet app from a deployed code-template.

A Spacemesh 0.2 transaction must include a signature generated by one of the two supported signature schemes, ED25519 or ED25519++.

---

Transaction Data Item

Transaction data item is binary data item encoded using XDR. It is used by other data items defined below to describe a SignedTransaction. Following are the data items and the binary layout for each of the three supported transaction types.

Simple Coin Transaction

struct SimpleCoinTx {
    unsigned int TTL; // 32-bit
    opaque Nonce[1];
    opaque Recipient[20];
    unsigned hyper Amount;
    unsigned hyper GasLimit;
    unsigned hyper GasPrice;
};

Call App Transaction

struct CallAppTx {
    unsigned int TTL; // 32-bit
    opaque Nonce[1];
    opaque AppAddress[20];
    unsigned hyper Amount;
    unsigned hyper GasLimit;
    unsigned hyper GasPrice;
    opaque CallData<>;
};

Spawn Transaction

struct SpawnAppTx {
    unsigned int TTL; // 32-bit
    opaque Nonce[1];
    opaque TemplateAddress[20];
    unsigned hyper Amount;
    unsigned hyper GasLimit;
    unsigned hyper GasPrice;
    opaque CallData<>;
};

---

Transaction Type Data Item

A type data item is a 1-byte enumeration that specifies a transaction type.

The least-significant-bit defines the signature scheme: 0 ⇨ ED25519; 1 ⇨ ED25519++.

The remaining 7 bits define the type of the internal transaction:

enum TransactionType {
    COIN_TX   = 0, // coin transaction
    EXEC_APP  = 1, // exec app transaction
    SPAWN_APP = 2, // spawn app
    // future types to be added here
};

The entire type byte can also be interpreted as a single enumeration, defined as follows:

enum TransactionAndSignatureType {
    COIN_TX_ED       = 0, // coin transaction / ed
    COIN_TX_EDPLUS   = 1, // coin transaction / ed++
    EXEC_APP_ED      = 2, // exec app transaction / ed
    EXEC_APP_EDPLUS  = 3, // exec app transaction / ed++
    SPAWN_APP_ED.    = 4, // spawn app / ed
    SPAWN_APP_EDPLUS = 5, // spawn app / ed++
    // future types to be added here
};

The Type Data Item is used in the data structures described below.

---

Transaction Authentication Message

TransactionAuthenticationMessage is an ephemeral data structure that is never transmitted over the network or stored in the database. It is constructed on-the-fly to sign transactions and verify transaction signatures.

struct TransactionAuthenticationMessage {
    opaque NetworkID[32];
    opaque Type[1];
    opaque TransactionData<>;
};

• NetworkID is a unique 32-byte identifier that is never transmitted, but is used to ensure that transactions aren't valid on more than one network. This prevent replay attacks and other bugs which may be caused by a node processing a transaction that was not created and signed for the network it is being added to.

• Type - Transaction type data item as defined in this spec.

• TransactionData - The transaction data item. e.g one of SimpleCoinTx, CallAppTx or SpawnAppTx as defined in this spec.

---

Signed Transaction Binary Format

When a transaction is stored or transmitted over the network, the following XDR format is used for a signed transaction:

struct SignedTransaction {
    opaque Type[1];
    opaque Signature[64];
    opaque TransactionData<>;
    opaque *PubKey[32]; // optional, depending on Type.
};

• Type - Transaction type data item as defined in this spec.

• Signature is a digital signature, using the specified signature scheme, of a TransactionAuthenticationMessage constructed from the transaction. An ED25519 or an ED25519++ signature is 64 bytes.

• TransactionData - The transaction data item, i.e., one of SimpleCoinTx, CallAppTx or SpawnAppTx as defined in this spec.

• PubKey - when ED25519 is used (and not ED25519++), the public ed key of the transaction signer. In ED25519++ the public key is extracted from the signed message and the signature.

Transaction ID

• The transaction id is not a field in the SignedTransaction object. It is calculated on the fly and used to index and reference transactions.
• Blocks contain a list of TransactionIDs and therefore this definition is part of the consensus rules.
• The TransactionID is the 32-byte SHA256 hash sum of the SignedTransaction.

---

Signing a Transaction

Input: Type, TransactionData, NetworkID, a signer. Output: SignedTransaction binary data item.

1. Create TransactionAuthenticationMessage for the transaction using the input, and get its XDR encoded binary data.
2. Hash the data using sha-512 to create a message digest for signature.
3. Sign the message digest using the signature scheme specified in the given transaction type and the signer's private key.
4. Create a SignedTransaction and return it XDR binary data.

Notes

• When ED25519 is used, the public key should be included in SignedTransaction.

• SignedTransaction doesn't include NetworkID. Both the signer and validator should have this data preconfigured.

• SignedTransaction is the transaction data that is sent on the Spacemesh network for processing. To submit a transaction, transmit its SignedTransaction via the network's gossip network.

---

Decoding and Verifying a Signed Transaction

Input: SignedTransaction, NetworkId. Output: Verified or rejected TransactionData.

1. Decode SignedTransaction and create an TransactionAuthenticationMessage using the input and the decoded data.
2. If the signature scheme is ed25519++ then extract the public key from the Signature and SignedTransaction and skip to step 4.
3. Hash TransactionAuthenticationMessage using sha512 to create a message digest. Use the ed25519 verify algorithm with the message digest as the input, e.g., ed25519_pub_key.verify(signature, message_digest) to verify the transaction.
4. Based on the transaction type, decode the transaction data into one of the three relevant native transaction data item as defined in this spec.

---

Implementation Notes

1. Smapp and CLIWallet, the Spacemesh reference user wallets, should be be updated to support creating transactions in the syntax defined in this document and to sign transactions with ed25519. Until the SVM-SDK is integrated in them, they should just mock SVM data in transactions so we are ready to integrate the SVM-SDK at a later time.
2. The Spacemesh Ledger SDK may need to be updated to support the new transactions syntax.
3. The Ledger SDK should be ported to GO (or updated via a GO wrapper) to support CLIWallet (which is written in GO), so users will be able to sign transactions created in CLIWallet in the Spacemesh Ledger App.
4. The Spacemesh Ledger App needs to be able to parse all new transactions binary encoding and display the required information on the device's screen for users and to sign the transactions according to the information in this document.

• Note that for Spacemesh 0.2 timeframe, the wallets do NOT need to sign transactions in ed25519++ signature scheme. We will add support for this signature scheme as soon as we have support for it in the Spacemesh Ledger App.