> For the complete documentation index, see [llms.txt](https://quantumwing.gitbook.io/quantumwing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumwing.gitbook.io/quantumwing/transactions/format.md).

# Transaction Format

Transaction format, Dilithium signing, and EVM-compatible addresses in QuantumWing

## Overview

QuantumWing transactions use **Dilithium Mode 3 signatures** (3293 bytes) with **EVM-compatible addresses** (0x...).

{% hint style="success" %}
**Compatibility**: EVM address format | **Security**: Quantum-safe Dilithium signatures | **Size**: \~3.5 KB per tx
{% endhint %}

## Transaction Structure

### Standard Transaction

```go
type Transaction struct {
    // Header fields
    Nonce    uint64   // Account nonce (prevents replay)
    GasPrice uint64   // Gas price in gwei
    GasLimit uint64   // Max gas to consume
    To       Address  // Recipient address (20 bytes)
    Value    *big.Int // Amount in wei
    Data     []byte   // Contract call data or empty
    
    // Quantum-safe signature fields
    DilithiumSignature []byte // 3293 bytes (Mode 3)
    DilithiumPublicKey []byte // 1952 bytes (Mode 3)
    
    // Derived fields (computed from signature)
    From Address // Sender address (derived from pubkey)
    Hash Hash    // Transaction hash (SHA3-256)
}
```

### Size Comparison

| Field          | QuantumWing      | Ethereum          |
| -------------- | ---------------- | ----------------- |
| **Header**     | \~100 bytes      | \~100 bytes       |
| **Signature**  | 3293 bytes       | 65 bytes          |
| **Public Key** | 1952 bytes       | 0 bytes (derived) |
| **Total**      | **\~5345 bytes** | **\~165 bytes**   |
| **Overhead**   | **32x larger**   | Baseline          |

{% hint style="info" %}
**Mitigation**: Signature aggregation planned for Q1 2026 will reduce tx size by \~90%.
{% endhint %}

## Transaction Types

### 1. **Simple Transfer**

Transfer QWING from one account to another.

```json
{
  "nonce": 42,
  "gasPrice": 20000000000,
  "gasLimit": 21000,
  "to": "0x1234567890abcdef1234567890abcdef12345678",
  "value": "1000000000000000000",
  "data": ""
}
```

**Gas Cost**: 21,000 gas (same as Ethereum)

### 2. **Contract Deployment**

Deploy a new smart contract (QWVM).

```json
{
  "nonce": 43,
  "gasPrice": 20000000000,
  "gasLimit": 1000000,
  "to": null,
  "value": "0",
  "data": "0x608060405234801561001057600080fd5b50..."
}
```

**Gas Cost**: 32,000 + contract\_size \* 200

### 3. **Contract Call**

Execute a contract method.

```json
{
  "nonce": 44,
  "gasPrice": 20000000000,
  "gasLimit": 100000,
  "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5",
  "value": "0",
  "data": "0xa9059cbb000000000000000000000000..."
}
```

**Gas Cost**: 21,000 + execution\_cost

## Signing Process

### Step 1: Create Unsigned Transaction

```go
import "github.com/quantumwing/protocol/blockchain/evm"

tx := &evm.Transaction{
    Nonce:    42,
    GasPrice: 20_000_000_000, // 20 gwei
    GasLimit: 21_000,
    To:       common.HexToAddress("0x1234567890abcdef1234567890abcdef12345678"),
    Value:    big.NewInt(1_000_000_000_000_000_000), // 1 QWING
    Data:     []byte{},
}
```

### Step 2: Serialize Transaction

Uses **SSZ (Simple Serialize)** encoding for deterministic hashing:

```go
import "github.com/quantumwing/protocol/blockchain/types/ssz"

// Serialize transaction
sszEncoded := ssz.Marshal(tx)

// Hash with SHA3-256
txHash := sha3.Sum256(sszEncoded)
```

**SSZ Benefits**:

* ✅ Deterministic (same input → same output)
* ✅ Fast encoding/decoding
* ✅ Merkleization support
* ✅ Used by Ethereum 2.0

### Step 3: Sign with Dilithium

```go
import "github.com/open-quantum-safe/liboqs-go/oqs"

// Initialize Dilithium signer
signer := oqs.Signature{}
defer signer.Clean()
signer.Init("Dilithium3", privateKey)

// Sign transaction hash
signature, err := signer.Sign(txHash[:])
if err != nil {
    return err
}

// Attach signature to transaction
tx.DilithiumSignature = signature       // 3293 bytes
tx.DilithiumPublicKey = publicKey       // 1952 bytes
```

### Step 4: Derive Sender Address

```go
// Derive EVM address from Dilithium public key
senderAddress := crypto.DilithiumToAddress(publicKey)
tx.From = senderAddress

// Compute final transaction hash
tx.Hash = sha3.Sum256(ssz.Marshal(tx))
```

### Complete Example

```go
package main

import (
    "fmt"
    "math/big"
    
    "github.com/quantumwing/protocol/blockchain/evm"
    "github.com/quantumwing/protocol/crypto/dilithium"
)

func main() {
    // 1. Load wallet
    wallet, err := dilithium.LoadWallet("wallet.json", "password")
    if err != nil {
        panic(err)
    }
    
    // 2. Create transaction
    tx := &evm.Transaction{
        Nonce:    wallet.GetNonce(),
        GasPrice: 20_000_000_000,
        GasLimit: 21_000,
        To:       common.HexToAddress("0x1234567890abcdef1234567890abcdef12345678"),
        Value:    big.NewInt(1_000_000_000_000_000_000),
        Data:     []byte{},
    }
    
    // 3. Sign transaction
    signedTx, err := wallet.SignTransaction(tx)
    if err != nil {
        panic(err)
    }
    
    // 4. Send to network
    hash, err := rpcClient.SendTransaction(signedTx)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Transaction sent: %s\n", hash.Hex())
}
```

## Transaction Hash Calculation

### Formula

```
TxHash = SHA3-256(SSZ(Transaction))
```

### SSZ Encoding Order

```
SSZ Root:
├─ Nonce (uint64)
├─ GasPrice (uint64)
├─ GasLimit (uint64)
├─ To (20 bytes)
├─ Value (32 bytes, big-endian)
├─ Data (variable length)
├─ DilithiumSignature (3293 bytes)
└─ DilithiumPublicKey (1952 bytes)
```

### Example

```go
// Transaction fields
tx := Transaction{
    Nonce:    42,
    GasPrice: 20_000_000_000,
    GasLimit: 21_000,
    To:       common.HexToAddress("0x1234567890abcdef1234567890abcdef12345678"),
    Value:    big.NewInt(1_000_000_000_000_000_000),
    Data:     []byte{},
    DilithiumSignature: signature,  // 3293 bytes
    DilithiumPublicKey: publicKey,  // 1952 bytes
}

// Compute hash
sszBytes := ssz.Marshal(tx)
txHash := sha3.Sum256(sszBytes)

fmt.Printf("Transaction Hash: 0x%x\n", txHash)
// Output: 0xabcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab
```

## Address Derivation

### From Dilithium Public Key → 0x Address

```go
func DilithiumToAddress(publicKey []byte) Address {
    // 1. Hash Dilithium public key (1952 bytes)
    hash := sha3.Sum256(publicKey)
    
    // 2. Take last 20 bytes
    address := hash[12:32]
    
    // 3. Return as 0x-prefixed hex
    return Address(address)
}
```

### Example

```
Dilithium Public Key (1952 bytes):
0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f...

SHA3-256 Hash:
0x000000000000000000000000742d35Cc6634C0532925a3b844Bc9e7595f0bEb5

EVM Address (last 20 bytes):
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5 ✅
```

## Nonce Management

### Sequential Nonces

Each account has a **nonce counter** starting at 0:

```go
// First transaction: nonce = 0
tx1 := &Transaction{Nonce: 0, ...}

// Second transaction: nonce = 1
tx2 := &Transaction{Nonce: 1, ...}

// Third transaction: nonce = 2
tx3 := &Transaction{Nonce: 2, ...}
```

{% hint style="danger" %}
**Critical**: Nonces must be sequential! If nonce 5 is sent before nonce 4, tx will be **rejected**.
{% endhint %}

### Get Current Nonce

```bash
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionCount",
    "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5", "latest"],
    "id": 1
  }'
```

**Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x2a"  // Nonce = 42
}
```

### Handling Nonce Gaps

If transaction fails, **reuse the same nonce**:

```go
// Transaction failed
tx1 := &Transaction{Nonce: 42, GasPrice: 10, ...}
// Status: Failed (insufficient gas)

// Resubmit with higher gas price
tx2 := &Transaction{Nonce: 42, GasPrice: 20, ...}  // Same nonce!
// Status: Success ✅
```

## Gas & Fees

### Gas Price

**Current**: 20 gwei (0.00000002 QWING) **Recommended**: Check `eth_gasPrice` API

```bash
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_gasPrice",
    "params": [],
    "id": 1
  }'
```

### Gas Limit

| Operation               | Gas Cost           |
| ----------------------- | ------------------ |
| **Simple Transfer**     | 21,000             |
| **Contract Deployment** | 32,000 + data      |
| **Contract Call**       | 21,000 + execution |
| **Storage Write**       | 20,000 per slot    |
| **Dilithium Verify**    | 50,000             |

### Total Fee Calculation

```
Total Fee = Gas Used × Gas Price

Example:
├─ Gas Used: 21,000
├─ Gas Price: 20 gwei
└─ Total Fee: 21,000 × 20 = 420,000 gwei = 0.00042 QWING
```

## Transaction Lifecycle

```mermaid
graph TD
    A[Create Transaction] --> B[Sign with Dilithium]
    B --> C[Submit to Mempool]
    C --> D{Valid?}
    D -->|No| E[Reject]
    D -->|Yes| F[Pending State]
    
    F --> G[Validator Selects Tx]
    G --> H[Include in Block Proposal]
    H --> I[Block Propagates]
    I --> J[Beacon Verifies Signatures]
    J --> K{Valid Block?}
    
    K -->|No| L[Orphan Block]
    K -->|Yes| M[Execution Layer Processes]
    M --> N{Execution Success?}
    
    N -->|No| O[Tx Failed, Gas Consumed]
    N -->|Yes| P[Tx Success, State Updated]
    
    O --> Q[Receipt: status=0]
    P --> R[Receipt: status=1]
    
    R --> S[Wait 64 Slots]
    S --> T[Finalized ✅]
```

### States

1. **Created** - Transaction signed locally
2. **Pending** - In mempool, waiting for inclusion
3. **Included** - In proposed block
4. **Confirmed** - Block accepted by network
5. **Finalized** - Irreversible (after 64 slots)

## Validation Rules

### Pre-Execution Checks

```go
func ValidateTransaction(tx *Transaction) error {
    // 1. Check signature
    if !dilithium.Verify(tx.Hash, tx.DilithiumSignature, tx.DilithiumPublicKey) {
        return ErrInvalidSignature
    }
    
    // 2. Verify sender address
    derivedAddr := crypto.DilithiumToAddress(tx.DilithiumPublicKey)
    if derivedAddr != tx.From {
        return ErrInvalidSender
    }
    
    // 3. Check nonce
    expectedNonce := state.GetNonce(tx.From)
    if tx.Nonce != expectedNonce {
        return ErrInvalidNonce
    }
    
    // 4. Check balance
    balance := state.GetBalance(tx.From)
    totalCost := tx.Value + (tx.GasLimit * tx.GasPrice)
    if balance < totalCost {
        return ErrInsufficientFunds
    }
    
    // 5. Check gas limit
    if tx.GasLimit < 21000 {
        return ErrGasTooLow
    }
    if tx.GasLimit > 40_000_000 {
        return ErrGasTooHigh
    }
    
    return nil
}
```

### Post-Execution Checks

```go
func FinalizeTransaction(tx *Transaction, receipt *Receipt) {
    // 1. Deduct gas fee
    gasFee := receipt.GasUsed * tx.GasPrice
    state.SubBalance(tx.From, gasFee)
    state.AddBalance(block.Proposer, gasFee)  // Reward proposer
    
    // 2. Increment nonce
    state.SetNonce(tx.From, tx.Nonce + 1)
    
    // 3. Transfer value (if success)
    if receipt.Status == 1 {
        state.SubBalance(tx.From, tx.Value)
        state.AddBalance(tx.To, tx.Value)
    }
}
```

## CLI Usage

### Send Transaction

```bash
quantum-wing wallet send \
  --from wallet.json \
  --to 0x1234567890abcdef1234567890abcdef12345678 \
  --amount 1.5 \
  --gas-price 20 \
  --gas-limit 21000 \
  --rpc http://localhost:8546
```

### Check Transaction Status

```bash
quantum-wing tx status \
  --hash 0xabcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab \
  --rpc http://localhost:8546
```

### Get Receipt

```bash
quantum-wing tx receipt \
  --hash 0xabcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab \
  --rpc http://localhost:8546
```

## Further Reading

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>✍️ Signing Process</strong></td><td>Deep dive into Dilithium signing</td><td><a href="/quantumwing/transactions/signing.md">Signing Process</a></td></tr><tr><td><strong>⛽ Gas &#x26; Fees</strong></td><td>Gas economics and pricing</td><td><a href="/quantumwing/transactions/gas-fees.md">Gas &amp; Fees</a></td></tr><tr><td><strong>📦 Transaction Pool</strong></td><td>Mempool management</td><td><a href="/quantumwing/transactions/mempool.md">Transaction Pool</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://quantumwing.gitbook.io/quantumwing/transactions/format.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.