MorphTx Technical Specification
Abstract
Morph is designed as a payment settlement layer — a high-performance L2 blockchain purpose-built for real-world payment and commerce use cases. To bridge the gap between on-chain transactions and off-chain payment systems, Morph introduces MorphTx (0x7F), a custom EIP-2718 typed transaction that extends the standard EIP-1559 DynamicFeeTx. MorphTx consolidates and extends the AltFeeTx transaction type introduced in the Emerald upgrade, evolving it into a unified transaction primitive:
Alternative Fee Transaction enables users to pay gas fees using on-chain registered ERC-20 tokens (e.g., USDT, USDC) instead of ETH. This removes a critical barrier for payment adoption — merchants and end users no longer need to hold native ETH to interact with the chain. Fee conversion happens at the protocol level using an on-chain oracle, eliminating any dependency on Paymaster contracts or external bundlers.
Reference Key introduces a 32-byte merchant-controlled index field embedded natively in the transaction structure. This field is designed to meet three requirements for production payment integration:
- Indexed query support — a dedicated on-chain index keyed by Reference allows off-chain systems to efficiently retrieve all transactions associated with a given order, batch, or session, without full chain scanning.
- Zero performance impact — the index is maintained asynchronously during block insertion and uses a prefix-ordered key layout, adding negligible overhead to the critical execution path.
- Merchant-friendly generation — a Reference can be any deterministic 32-byte value: a keccak256 hash of an order ID, a UUID, or a composite business key. No smart contract interaction is required to register or use a Reference.
EIP-7702 authorizations, added by MorphTx V2 in the Celadon upgrade, let the same transaction carry an authorizationList. V2 keeps Alt Fee, Reference, and Memo. An authorization list on its own, with no Morph field, remains a standard SetCode transaction (0x04).
Together, these features make MorphTx the foundational transaction primitive for payment settlement on Morph: token-denominated fees reduce friction for merchants and users, while Reference-based indexing provides the traceability and reconciliation primitives that payment systems require.
1. Introduction
1.1 Background
Standard Ethereum transactions were designed for general-purpose computation. They require ETH for gas and offer no native mechanism for linking on-chain activity to off-chain business context. For payment use cases — where merchants accept stablecoins, reconcile orders, and integrate with existing financial systems — this creates two fundamental gaps:
- Gas friction: End users and merchants must acquire and manage ETH solely to pay transaction fees, even when the actual transfer is denominated in USDT or USDC.
- Traceability gap: There is no protocol-level way to tag a transaction with a business identifier (e.g., an order ID) and later query all transactions sharing that identifier. Applications resort to event logs, off-chain indexers, or custom smart contracts — all of which add complexity, latency, and cost.
1.2 From AltFeeTx to MorphTx
The Emerald upgrade introduced AltFeeTx (type 0x7F) — Morph's first custom transaction type, enabling gas payment with ERC-20 tokens at the protocol level. This solved the gas friction problem, but the transaction structure had no room for business-context fields.
The Jade upgrade evolves AltFeeTx into MorphTx — a unified, versioned transaction type that retains full Alt Fee support and adds two new capabilities:
| What's New in Jade | Description |
|---|---|
| Reference Key | A 32-byte field for tagging transactions with merchant-defined identifiers, with built-in on-chain indexing |
| Memo | An optional up to 64-byte note attached to the transaction |
| Versioned format | V0 (Emerald-era Alt Fee) and V1 (Jade-era full feature set) coexist with backward-compatible encoding |
| ETH-only MorphTx | V1 allows FeeTokenID = 0, so you can use Reference/Memo without Alt Fee |
The Celadon upgrade (morph-v2.2.7) adds V2:
| What's New in Celadon | Description |
|---|---|
| Authorization List | EIP-7702 authorizationList on MorphTx. An empty list is valid, and the transaction stays V2 |
| Contract creation rule | A non-empty authorization list cannot create a contract (to must be set) |
| Alt Fee refund rounding | Charges still round up. Refunds add the charge-time rounding credit and round down, for every Alt Fee transaction |
The type byte remains 0x7F — existing AltFeeTx transactions are valid V0 MorphTx with no migration required. V0, V1, and V2 share that type byte and are distinguished by the payload prefix.
1.3 When to Use MorphTx
| Scenario | Use MorphTx? | Version | Notes |
|---|---|---|---|
| Pay gas with USDT/USDC | Yes | V0, V1, or V2 | Set feeTokenID to the registered token ID. eth_sendTransaction builds V1 unless an authorization list selects V2 |
| Tag a payment with an order ID | Yes | V1 or V2 | Set reference to keccak256(orderId) |
| Both: stablecoin gas + order tracking | Yes | V1 or V2 | Set feeTokenID + reference |
| Attach a human-readable memo | Yes | V1 or V2 | Set memo (up to 64 bytes) |
| Morph fields plus EIP-7702 authorizations | Yes | V2 | Set authorizationList together with feeTokenID, reference, or memo |
| EIP-7702 only, no Morph fields | No | — | Use a standard SetCode transaction (0x04) |
| Standard ETH transfer, no extras | No | — | Use a regular EIP-1559 transaction |
2. MorphTx Fields
MorphTx includes all standard EIP-1559 fields plus the following Morph-specific extensions:
2.1 Extension Fields
| Field | Type | Required | Description |
|---|---|---|---|
version | uint8 | Yes | 0 for V0, 1 for V1, 2 for V2. On eth_sendTransaction this is inferred and is not an input |
feeTokenID | uint16 | V0: Yes (>0) / V1–V2: Optional | On-chain registered ERC-20 token ID. 0 = pay with ETH |
feeLimit | big.Int | Optional | Token fee cap when using Alt Fee. If unset, the sender's token balance is the limit |
reference | [32]byte | V1–V2, optional | 32-byte index key for transaction tagging and querying |
memo | []byte | V1–V2, optional | Free-form note, max 64 bytes |
authorizationList | []SetCodeAuthorization | V2 only, optional | EIP-7702 authorizations. An empty list is legal on a V2 payload; eth_sendTransaction selects V2 only when the list is non-empty |
2.2 Version Rules at a Glance
| V0 (Emerald) | V1 (Jade) | V2 (Celadon) | |
|---|---|---|---|
| Alt Fee | Required (feeTokenID must be > 0) | Optional (feeTokenID can be 0) | Same as V1 |
| Reference | Not available | Optional | Optional |
| Memo | Not available | Optional (≤ 64 bytes) | Optional (≤ 64 bytes) |
| Authorization List | Not available | Not available | Optional, including empty |
| FeeLimit when feeTokenID = 0 | N/A (feeTokenID must be > 0) | Must be nil or 0 | Must be nil or 0 |
| Contract creation | Allowed | Allowed | Rejected when the authorization list is non-empty |
2.3 Gas Pricing
MorphTx uses the same EIP-1559 fee model as standard Ethereum transactions:
maxFeePerGas— maximum total fee per gas unitmaxPriorityFeePerGas— tip to the sequencer
Do not set gasPrice on a MorphTx. If gasPrice is present, the RPC layer will silently downgrade the transaction to a legacy type, discarding all Morph fields.
3. Alt Fee: Pay Gas with ERC-20 Tokens
3.1 How It Works
- You set
feeTokenIDto the on-chain registered ID of a supported token (e.g., USDT). - Optionally set
feeLimitto the maximum token amount you authorize for gas payment. If unset, the sender's token balance is used as the limit. - The protocol calculates the gas cost in ETH (standard EIP-1559), then converts it to the token using an on-chain oracle rate:
tokenAmount = ⌈(ethAmount × tokenScale) / tokenRate⌉
- The token amount is deducted from your balance. Unused gas is refunded in the same token. Before Celadon the refund uses the same ceiling. From Celadon onward the refund adds the charge-time rounding credit and rounds down. See Gas Refund.
Token rates are stored in the Token Registry system contract at 0x5300000000000000000000000000000000000021.
3.2 Constraints
- The token must be registered and in active state on-chain
feeLimitacts as a safety cap — the transaction reverts if the actual cost exceeds it- In V0,
feeTokenIDmust be > 0 (Alt Fee is mandatory) - In V1 and V2,
feeTokenIDcan be 0 (ETH), but thenfeeLimitmust be nil or 0
3.3 Receipt Fee Fields
After execution, the receipt includes:
| Field | Description |
|---|---|
feeRate | ETH/token exchange rate used at execution time (Alt Fee only) |
tokenScale | Exchange rate precision scale (Alt Fee only) |
l1Fee | L1 data fee (also converted if using Alt Fee) |
4. Reference Key: Transaction Tagging & Querying
4.1 What Is a Reference?
A Reference is a 32-byte value you embed in a V1 or V2 MorphTx to tag it with a business identifier. Multiple transactions can share the same Reference, and you can query all of them via a dedicated RPC method.
4.2 Generating a Reference
A Reference can be any 32-byte value. Common patterns:
// Hash an order ID
reference = keccak256("order-2026-03-30-00142")
// Use a UUID (zero-padded to 32 bytes)
reference = bytes32(uuid)
// Composite key
reference = keccak256(abi.encodePacked(merchantId, sessionId))
No on-chain registration is needed — just pick a deterministic scheme and start using it.
4.3 Querying by Reference
Use the morph_getTransactionHashesByReference RPC to retrieve all transactions tagged with a given Reference:
Request:
{
"jsonrpc": "2.0",
"method": "morph_getTransactionHashesByReference",
"params": [{
"reference": "0x1234...cdef",
"offset": "0x0",
"limit": "0x64"
}],
"id": 1
}
Response (sorted by block timestamp + tx index, ascending):
{
"result": [
{
"transactionHash": "0xabc...",
"blockNumber": "0x123",
"blockTimestamp": "0x66012345",
"transactionIndex": "0x0"
},
{
"transactionHash": "0xdef...",
"blockNumber": "0x125",
"blockTimestamp": "0x66012400",
"transactionIndex": "0x2"
}
]
}
Pagination constraints:
limit: max 100 per requestoffset: max 10000
4.4 Use Cases
| Scenario | Reference Value | How It Helps |
|---|---|---|
| Payment reconciliation | keccak256(orderId) | Query all txs for a given order — payments, refunds, adjustments |
| Batch settlement | keccak256(batchId) | Track all transactions in a settlement batch |
| Session tracking | keccak256(sessionId) | Link multiple on-chain actions within a user session |
| Cross-system audit | keccak256(externalSystemId) | Bridge on-chain and off-chain records by a shared key |
5. SDK Development Guide (Go)
5.1 Sending a V1 MorphTx with Alt Fee + Reference
import (
"math/big"
"github.com/morph-l2/go-ethereum/common"
"github.com/morph-l2/go-ethereum/core/types"
"github.com/morph-l2/go-ethereum/crypto"
)
// Construct unsigned transaction
ref := common.HexToReference("0xabcdef...")
memo := []byte("payment for order #123")
tx := types.NewTx(&types.MorphTx{
ChainID: big.NewInt(2818),
Nonce: 1,
GasTipCap: big.NewInt(1e9),
GasFeeCap: big.NewInt(2e9),
Gas: 21000,
To: &toAddr,
Value: big.NewInt(1e18),
FeeTokenID: 1, // USDT token ID
FeeLimit: big.NewInt(5e17), // max 0.5 USDT
Version: types.MorphTxVersion1,
Reference: &ref,
Memo: &memo,
})
// Sign and send
signer := types.NewEmeraldSigner(big.NewInt(2818))
signedTx, _ := types.SignTx(tx, signer, privateKey)
err := client.SendTransaction(ctx, signedTx)
5.2 Sending a V1 MorphTx with ETH Gas + Reference Only
// No Alt Fee — just Reference and Memo
ref := common.HexToReference("0x1234...")
tx := types.NewTx(&types.MorphTx{
ChainID: big.NewInt(2818),
Nonce: 1,
GasTipCap: big.NewInt(1e9),
GasFeeCap: big.NewInt(2e9),
Gas: 21000,
To: &toAddr,
Value: big.NewInt(1e18),
FeeTokenID: 0, // ETH
Version: types.MorphTxVersion1,
Reference: &ref,
})
signer := types.NewEmeraldSigner(big.NewInt(2818))
signedTx, _ := types.SignTx(tx, signer, privateKey)
5.3 Sending a V2 MorphTx with Alt Fee + Reference + EIP-7702 Authorizations
ref := common.HexToReference("0xabcdef...")
memo := []byte("payment for order #123")
tx := types.NewTx(&types.MorphTx{
ChainID: big.NewInt(2818),
Nonce: 1,
GasTipCap: big.NewInt(1e9),
GasFeeCap: big.NewInt(2e9),
Gas: 100000,
To: &toAddr,
Value: big.NewInt(0),
FeeTokenID: 1, // USDT token ID
FeeLimit: big.NewInt(5e17), // max 0.5 USDT
Version: types.MorphTxVersion2,
Reference: &ref,
Memo: &memo,
AuthList: []types.SetCodeAuthorization{signedAuth}, // EIP-7702 authorization list
})
signer := types.NewEmeraldSigner(big.NewInt(2818))
signedTx, _ := types.SignTx(tx, signer, privateKey)
err := client.SendTransaction(ctx, signedTx)
5.4 Querying Transactions by Reference
client, _ := ethclient.Dial("http://localhost:8545")
results, err := client.GetTransactionHashesByReference(ctx,
common.HexToReference("0x1234..."),
nil, // offset (default 0)
nil, // limit (default 100)
)
for _, r := range results {
fmt.Printf("tx: %s block: %d\n", r.TransactionHash.Hex(), r.BlockNumber)
}
5.5 Using Contract Bindings (accounts/abi/bind)
auth, _ := bind.NewKeyedTransactorWithChainID(key, chainID)
auth.FeeTokenID = 1
auth.FeeLimit = big.NewInt(1000000)
ref := common.HexToReference("0x1234...")
auth.Reference = &ref
memo := []byte("payment for order #123")
auth.Memo = &memo
// Any contract call will now use MorphTx V1
tx, err := contract.Transfer(auth, recipient, amount)
TransactOpts no longer takes a version. The binding derives it: MorphTx defaults to V1, and a non-empty AuthorizationList selects V2. When FeeTokenID != 0, or Reference/Memo is set, the binding constructs a MorphTx. An authorization list with none of those fields constructs a standard SetCode transaction.
5.6 Using CallMsg for Estimation
msg := ethereum.CallMsg{
From: fromAddr,
To: &toAddr,
Gas: 0,
GasFeeCap: big.NewInt(2e9),
GasTipCap: big.NewInt(1e9),
Value: big.NewInt(0),
Data: calldata,
FeeTokenID: 1,
FeeLimit: big.NewInt(5e17),
}
gasEstimate, err := client.EstimateGas(ctx, msg)
When feeTokenID is present in the JSON-RPC request, eth_estimateGas checks the user's token balance (not ETH) and converts the L1 Data Fee to token units. The node infers V1 from feeTokenID. ethclient does not currently forward CallMsg Morph fields, so send this shape as a raw eth_estimateGas parameter.
6. Other Language SDK Guide
6.1 Transaction Type
- EIP-2718 type byte:
0x7F(127)
6.2 JSON-RPC Field Mapping
| Go Field | JSON Field | Type | Notes |
|---|---|---|---|
GasTipCap | maxPriorityFeePerGas | hex big int | |
GasFeeCap | maxFeePerGas | hex big int | |
FeeTokenID | feeTokenID | hex uint16 | |
FeeLimit | feeLimit | hex big int | |
Version | version | hex uint | Response only, V1+ (omitempty). Not an eth_sendTransaction input |
Reference | reference | hex bytes32 | V1+ only (omitempty) |
Memo | memo | hex bytes | V1+ only (omitempty) |
AuthList | authorizationList | authorization array | V2 only. An empty list is encoded as [] |
6.3 Sending via eth_sendTransaction
{
"from": "0x...",
"to": "0x...",
"maxFeePerGas": "0x...",
"maxPriorityFeePerGas": "0x...",
"gas": "0x...",
"value": "0x...",
"data": "0x...",
"feeTokenID": "0x1",
"feeLimit": "0x...",
"reference": "0x1234...cdef",
"memo": "0x68656c6c6f"
}
Auto-detection: Setting feeTokenID > 0, a non-zero reference, or a non-empty memo triggers MorphTx construction. authorizationList alone selects a SetCode transaction (0x04).
Version inference: eth_sendTransaction does not accept version. A non-empty authorizationList on a MorphTx selects V2. Every other unsigned MorphTx is V1, including an Alt Fee transaction that used to be built as V0. Signed V0 payloads remain valid through eth_sendRawTransaction.
6.4 Reading MorphTx Fields from Responses
eth_getTransactionByHash returns:
{
"type": "0x7f",
"chainId": "0xb02",
"feeTokenID": "0x1",
"feeLimit": "0x...",
"version": "0x1",
"reference": "0x1234...cdef",
"memo": "0x68656c6c6f",
...
}
V0 transactions omit
version,reference,memo, andauthorizationList. Ifversionis absent, assume V0. V2 responses includeauthorizationList, encoded as[]when the list is empty.
7. RPC Reference
7.1 Standard eth Namespace
| Method | MorphTx Behavior |
|---|---|
eth_sendTransaction | Accepts Morph fields; auto-detects type and version |
eth_sendRawTransaction | Accepts RLP-encoded 0x7F || payload; auto-decodes V0/V1/V2 |
eth_getTransactionByHash | Returns Morph extension fields in response |
eth_getTransactionReceipt | Includes feeTokenID, feeRate, tokenScale, l1Fee, etc. |
eth_estimateGas | Considers Alt Fee token balance and L1 fee conversion |
eth_call | Supports Morph fields in CallMsg |
7.2 morph Namespace
| Method | Description |
|---|---|
morph_getTransactionHashesByReference | Query transactions by Reference key (paginated) |
morph_estimateL1DataFee | Estimate L1 data fee (Morph fields affect serialized size) |
7.3 Receipt Extension Fields
| Field | Type | Condition | Description |
|---|---|---|---|
feeTokenID | uint16 | All MorphTx | Token ID used (0 = ETH) |
feeLimit | big.Int | All MorphTx | Token fee cap (may be nil) |
feeRate | big.Int | Alt Fee only (feeTokenID > 0) | ETH/token rate at execution |
tokenScale | big.Int | Alt Fee only (feeTokenID > 0) | Rate precision scale |
l1Fee | big.Int | All MorphTx | L1 data fee |
version | uint8 | V1+ only | Transaction version |
reference | bytes32 | V1+ only | Reference key |
memo | bytes | V1+ only | Memo |
authorizationList is a transaction field, not a receipt field. Read it from eth_getTransactionByHash.
8. Common Pitfalls
8.1 gasPrice Silently Overrides MorphTx
If you set both gasPrice AND MorphTx fields (e.g., feeTokenID), the RPC layer treats the transaction as a LegacyTx and discards all Morph fields without error.
Fix: Always use maxFeePerGas / maxPriorityFeePerGas.
8.2 V0 vs V1 and V2 FeeTokenID Semantics
| V0 | V1 and V2 | |
|---|---|---|
FeeTokenID == 0 | Invalid | Valid (use ETH) |
| Purpose | Alt Fee only | General-purpose |
If migrating from V0 to V1 or V2, FeeTokenID is no longer required. A non-zero FeeLimit with FeeTokenID == 0 returns ErrMorphTxIllegalExtraParams.
8.3 Missing version in V0 Responses
V0 transactions omit version, reference, memo, and authorizationList from RPC responses (omitempty). Your SDK must handle missing fields:
versionabsent → V0referenceabsent → nilmemoabsent → nilauthorizationListonly appears on V2 responses (encoded as[]when empty)
8.4 V1 Transactions Before Jade Fork
V1 transactions are rejected everywhere before Jade fork activation — eth_sendTransaction, eth_sendRawTransaction, tx pool, and block validation will all refuse them.
8.5 V1 and V2 Signing Hashes Include Nil Fields
In the V1 and V2 signing hashes, reference and memo participate in RLP encoding even when nil (nil encodes as 0x80). V2 also includes authorizationList. Other language SDKs must handle this correctly — omitting nil fields from the signing hash will produce an invalid signature.
8.6 V2 Transactions Before the Celadon Fork
V2 transactions are rejected before Celadon activation — eth_sendTransaction, eth_sendRawTransaction, the tx pool, and block validation all return ErrMorphTxV2NotYetActive. A reorg behind the Celadon boundary removes V2 transactions from the tx pool.
9. Fork Timeline & Compatibility
MorphTx is enabled across three forks. Timestamps below match go-ethereum morph-v2.2.7.
Timeline ──────────────────────────────────────────────────────────────────►
│ │ │ │
│ Emerald │ Jade │ Celadon │
│ Fork │ Fork │ Fork │
▼ ▼ ▼ │
────┼───────────────┼────────────────┼────────────────┼──
│ │ │ │
│ MorphTxType │ MorphTx V1 │ MorphTx V2 │
│ signer │ enabled │ enabled │
│ enabled │ (V0 + V1) │ (V0 + V1 + V2)│
│ (V0 only) │ │ │
9.1 Emerald Fork
MorphTxType(0x7F) registered in the signer- Only V0 available (V1 and V2 rejected by tx pool and block validator)
- EIP-1559 must already be active
9.2 Jade Fork
- V1 transactions accepted by tx pool and block validation
- Reference index system activated
- On reorg past the Jade boundary, the tx pool removes all V1 transactions
9.3 Fork Configuration
Hoodi testnet:
{
"emeraldTime": 1766988000,
"jadeForkTime": 1774418400,
"celadonTime": 1793167200
}
| Fork | Timestamp | Activation (UTC) |
|---|---|---|
| Emerald | 1766988000 | 2025-12-29 06:00 |
| Jade | 1774418400 | 2026-03-25 06:00 |
| Celadon | 1793167200 | 2026-10-28 06:00 |
Mainnet:
{
"emeraldTime": 1767765600,
"jadeForkTime": 1775628000,
"celadonTime": 1793772000
}
| Fork | Timestamp | Activation (UTC) |
|---|---|---|
| Emerald | 1767765600 | 2026-01-07 06:00 |
| Jade | 1775628000 | 2026-04-08 06:00 |
| Celadon | 1793772000 | 2026-11-04 06:00 |
9.4 Celadon Fork
- V2 transactions accepted by the tx pool and block validation
- Alt Fee refunds switch to floor rounding with the charge-time rounding credit
- On reorg past the Celadon boundary, the tx pool removes all V2 transactions
10. Internal: Data Structures
10.1 Core Struct
Source: core/types/morph_tx.go
type MorphTx struct {
// ===== Same base fields as DynamicFeeTx =====
ChainID *big.Int
Nonce uint64
GasTipCap *big.Int // maxPriorityFeePerGas
GasFeeCap *big.Int // maxFeePerGas
Gas uint64
To *common.Address // nil = contract creation
Value *big.Int
Data []byte
AccessList AccessList
// ===== Morph extension fields =====
Version uint8 // 0=V0, 1=V1, 2=V2
FeeTokenID uint16 // ERC-20 token ID (0=ETH)
FeeLimit *big.Int // Token fee cap
Reference *common.Reference // 32-byte reference key (V1 and V2)
Memo *[]byte // Note (V1 and V2, ≤ 64 bytes)
AuthList []SetCodeAuthorization // EIP-7702 authorizations (V2 only)
// ===== Signature values =====
V *big.Int
R *big.Int
S *big.Int
}
10.2 Dependent Types
| Type | Defined in | Description |
|---|---|---|
common.Reference | common/types.go | [32]byte, supports Hex/JSON/GraphQL serialization |
common.ReferenceLength | common/types.go | Constant 32 |
common.MaxMemoLength | common/types.go | Constant 64 |
10.3 Version Validation
Source: core/types/transaction.go → ValidateMorphTxVersion()
| Version | FeeTokenID | FeeLimit | Reference | Memo | AuthList | Valid? |
|---|---|---|---|---|---|---|
| V0 | Must be > 0 | Optional | Must be nil | Must be nil | Must be empty | ✅ |
| V0 | = 0 | - | - | - | - | ❌ ErrMorphTxV0IllegalExtraParams |
| V0 | > 0 | - | Non-empty | - | - | ❌ ErrMorphTxV0IllegalExtraParams |
| V0 or V1 | - | - | - | - | Non-empty | ❌ ErrMorphTxAuthListRequiresV2 |
| V1 | Any | nil or 0 when FeeTokenID = 0 | Any | ≤ 64B | Empty | ✅ |
| V2 | Any | nil or 0 when FeeTokenID = 0 | Any | ≤ 64B | Any, including empty | ✅ |
| V1 or V2 | = 0 | > 0 | - | - | - | ❌ ErrMorphTxIllegalExtraParams |
| V1 or V2 | - | - | - | > 64B | - | ❌ ErrMemoTooLong |
| V2 | - | - | - | - | Non-empty and to == nil | ❌ ErrMorphTxV2ContractCreation |
10.4 Error Types
| Error | Meaning |
|---|---|
ErrMorphTxV0IllegalExtraParams | V0: FeeTokenID=0 or Reference/Memo set |
ErrMorphTxIllegalExtraParams | FeeTokenID=0 but FeeLimit>0. Applies to V1 and V2 |
ErrMorphTxAuthListRequiresV2 | authorizationList set on V0 or V1 |
ErrMorphTxV2ContractCreation | V2 authorization list is non-empty and to is nil |
ErrMorphTxUnsupportedVersion | Unsupported version number |
ErrMorphTxV1NotYetActive | V1 submitted before the Jade fork |
ErrMorphTxV2NotYetActive | V2 submitted before the Celadon fork |
ErrMemoTooLong | Memo exceeds 64 bytes |
11. Internal: Encoding/Decoding (Wire Format)
11.1 Wire Format Overview
MorphTx follows the EIP-2718 envelope: type byte + inner payload
┌─────────────────────────────────────────────────────────┐
│ Full wire format (MarshalBinary output) │
├──────┬──────────────────────────────────────────────────┤
│ 0x7F │ inner payload (generated by encode()) │
│txType│ │
├──────┴──────────────────────────────────────────────────┤
│ │
│ V0 inner payload: │
│ ┌─────────────────────────────────────────────┐ │
│ │ RLP([chainID, nonce, gasTipCap, gasFeeCap, │ │
│ │ gas, to, value, data, accessList, │ │
│ │ feeTokenID, feeLimit, v, r, s]) │ │
│ │ First byte >= 0xC0 (RLP list prefix) │ │
│ │ 14 fields total │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ V1 inner payload: │
│ ┌────┬────────────────────────────────────────┐ │
│ │0x01│ RLP([chainID, nonce, gasTipCap, │ │
│ │ver │ gasFeeCap, gas, to, value, data, │ │
│ │ │ accessList, feeTokenID, feeLimit, │ │
│ │ │ reference, memo, v, r, s]) │ │
│ │ │ 16 fields total │ │
│ └────┴────────────────────────────────────────┘ │
│ │
│ V2 inner payload: │
│ ┌────┬────────────────────────────────────────┐ │
│ │0x02│ RLP([chainID, nonce, gasTipCap, │ │
│ │ver │ gasFeeCap, gas, to, value, data, │ │
│ │ │ accessList, feeTokenID, feeLimit, │ │
│ │ │ reference, memo, authorizationList,│ │
│ │ │ v, r, s]) │ │
│ │ │ 17 fields total │ │
│ └────┴ ────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
11.2 V0 Encoding
Format: 0x7F || RLP([14 fields])
Field order:
0. chainID 1. nonce 2. gasTipCap 3. gasFeeCap
4. gas 5. to 6. value 7. data
8. accessList 9. feeTokenID 10. feeLimit 11. v
12. r 13. s
Constraint: feeTokenID must be non-zero.
11.3 V1 Encoding
Format: 0x7F || 0x01 || RLP([16 fields])
Field order:
0. chainID 1. nonce 2. gasTipCap 3. gasFeeCap
4. gas 5. to 6. value 7. data
8. accessList 9. feeTokenID 10. feeLimit 11. reference
12. memo 13. v 14. r 15. s
Key details:
- The version byte (
0x01) is a prefix, NOT inside the RLP list referenceandmemouse[]bytein RLP; empty =0x80
11.4 V2 Encoding
Format: 0x7F || 0x02 || RLP([17 fields])
Field order:
0. chainID 1. nonce 2. gasTipCap 3. gasFeeCap
4. gas 5. to 6. value 7. data
8. accessList 9. feeTokenID 10. feeLimit 11. reference
12. memo 13. authorizationList
14. v 15. r 16. s
Key details:
- The version byte (
0x02) is a prefix, NOT inside the RLP list authorizationListuses the EIP-7702 authorization RLP layout- An empty list is legal. A non-empty list requires
toto be set
11.5 Version Detection
firstByte = inner_payload[0]
if firstByte >= 0xC0 or firstByte == 0x00:
→ V0 (first byte is RLP list prefix)
elif firstByte == 0x01:
→ V1 (first byte is version)
elif firstByte == 0x02:
→ V2 (first byte is version)
else:
→ Unsupported version
V0's RLP list prefix (>= 0xC0) does not overlap the V1 (0x01) or V2 (0x02) version bytes.
11.6 Encoding & Decoding Paths
Encoding:
Transaction.MarshalBinary() → encodeTyped(buf)
├→ buf.WriteByte(0x7F)
└→ MorphTx.encode(buf)
rlp.Encode(w, morphTx) → MorphTx.EncodeRLP(w)
└→ MorphTx.encode(buf) // same function, identical output
Decoding:
Transaction.UnmarshalBinary(bytes) → decodeTyped(bytes)
├→ bytes[0] == 0x7F
└→ MorphTx.decode(bytes[1:]) // version detection + decode
rlp.Decode(r, &morphTx) → MorphTx.DecodeRLP(stream)
├→ stream.Kind() == List → V0
├→ version byte 0x01 + stream.Raw() → V1
└→ version byte 0x02 + stream.Raw() → V2
11.7 Transaction Hash
V0: keccak256(0x7F || RLP([14 fields including V,R,S]))
V1: keccak256(0x7F || 0x01 || RLP([16 fields including V,R,S]))
V2: keccak256(0x7F || 0x02 || RLP([17 fields including V,R,S]))
12. Internal: Signing Mechanism
12.1 Signer Requirements
// Recommended
signer := types.NewEmeraldSigner(chainID)
// Auto-selected (Emerald must be active)
signer := types.MakeSigner(config, blockNumber, blockTime)
// Latest signer for chain
signer := types.LatestSignerForChainID(chainID)
12.2 Signing Hash
The signing hash excludes V/R/S signature values.
V0 (11 fields):
sigHash = keccak256(0x7F || rlp([
chainID, nonce, gasTipCap, gasFeeCap, gas, to, value, data,
accessList, feeTokenID, feeLimit
]))
V1 (14 fields):
sigHash = keccak256(0x7F || rlp([
chainID, nonce, gasTipCap, gasFeeCap, gas, to, value, data,
accessList, feeTokenID, feeLimit, version, reference, memo
]))
V1 adds version, reference, and memo. Nil pointers encode as RLP empty string (0x80).
V2 (15 fields):
sigHash = keccak256(0x7F || rlp([
chainID, nonce, gasTipCap, gasFeeCap, gas, to, value, data,
accessList, feeTokenID, feeLimit, version, reference, memo,
authorizationList
]))
Versions after V1, including V2, use this latest signing payload. The version byte inside the payload keeps an unknown version from verifying as V2.
12.3 Signing Flow
types.SignTx(tx, signer, privateKey)
├→ h = signer.Hash(tx)
│ └→ MorphTx.sigHash(chainID)
│ └→ v0SigHash, v1SigHash, or v2SigHash
├→ sig = crypto.Sign(h[:], privateKey) // 65 bytes
└→ tx.WithSignature(signer, sig)
├→ R = sig[0:32]
├→ S = sig[32:64]
└→ V = sig[64] (0 or 1)
12.4 V/R/S Specification
- V: 0 or 1 (recovery identifier; add 27 for
ecrecover) - Encoding:
R (32B) || S (32B) || V (1B)— standard 65 bytes
12.5 Other Language Signing
# V0 signing hash
sig_hash = keccak256(
[0x7F] + rlp_encode([
chain_id, nonce, max_priority_fee, max_fee, gas_limit,
to, value, data, access_list, fee_token_id, fee_limit
])
)
# V1 signing hash
sig_hash = keccak256(
[0x7F] + rlp_encode([
chain_id, nonce, max_priority_fee, max_fee, gas_limit,
to, value, data, access_list, fee_token_id, fee_limit,
version, reference, memo
])
)
# V2 signing hash
sig_hash = keccak256(
[0x7F] + rlp_encode([
chain_id, nonce, max_priority_fee, max_fee, gas_limit,
to, value, data, access_list, fee_token_id, fee_limit,
version, reference, memo, authorization_list
])
)
- V value: 0 or 1 (NOT 27/28)
- Nil
reference/memomust encode as0x80in the signing hash - V2
authorization_listis included even when empty
13. Internal: Reference Index Storage
13.1 Storage Mechanism
Source: core/rawdb/accessors_reference_index.go
| Property | Value |
|---|---|
| Write timing | Block insertion (core/blockchain.go → maintainReferenceIndex) |
| Index key | prefix + reference(32B) + blockTimestamp(8B) + txIndex(8B) + txHash(32B) |
| Value | Empty (leverages key ordering for range queries) |
| Sort order | Ascending by blockTimestamp + txIndex |
| Reorg handling | Written on insertion, deleted on rollback |
13.2 Design Rationale
- Prefix-ordered keys enable efficient range scans without secondary indexes
- Empty values minimize storage overhead — only the key matters
- Asynchronous maintenance during block insertion avoids adding latency to the execution path
Appendix: Source File Index
| File | Responsibility |
|---|---|
core/types/morph_tx.go | MorphTx struct, encoding/decoding, signing hash |
core/types/transaction.go | TxData interface, type constant (0x7F), version validation |
core/types/transaction_signing.go | Signer interface, modernSigner, NewEmeraldSigner |
core/types/transaction_marshalling.go | JSON serialization/deserialization |
core/types/receipt.go | Receipt struct and Morph extension fields |
internal/ethapi/transaction_args.go | RPC param handling, version inference |
internal/ethapi/api.go | RPCTransaction, SendTransaction, PublicMorphAPI |
core/tx_pool.go | Tx pool validation, Jade/Celadon fork checks, V1/V2 cleanup |
core/block_validator.go | Block validation MorphTx checks |
core/state_processor.go | Post-execution receipt population |
core/state_transition.go | Alt Fee deduction and refund logic |
core/blockchain.go | Reference index maintenance |
core/rawdb/accessors_reference_index.go | Reference index read/write |
accounts/abi/bind/base.go | Contract binding TransactOpts |
ethclient/ethclient.go | Go client wrapper |
params/config.go | EmeraldTime, JadeForkTime, CeladonTime |
common/types.go | Reference type, MaxMemoLength |