Skip to main content

MorphTx Developer Guide

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:

  1. 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.
  2. 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.
  3. 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. New Transaction Type​

MorphTx is a custom EIP-2718 typed transaction for Morph L2, with type ID 0x7F (127). It extends the standard DynamicFeeTx (EIP-1559) with the following capabilities:

FeatureDescription
Alt Fee (Alternative Token Gas Fee)Pay gas fees with on-chain registered ERC-20 tokens instead of ETH
Reference32-byte transaction reference key for on-chain indexing and querying
MemoUp to 64-byte transaction note
Authorization List (V2, Celadon)EIP-7702 authorizationList. An empty list is valid and the transaction stays V2

1.1 Version System​

MorphTx uses a multi-version encoding format for backward compatibility:

VersionConstantStatusDescription
V0MorphTxVersion0 = 0Available after Emerald forkLegacy format, compatible with original AltFeeTx. Supports Alt Fee only — no Version/Reference/Memo fields. FeeTokenID must be > 0
V1MorphTxVersion1 = 1Available after Jade forkSupports Alt Fee + Reference + Memo. All Morph extension fields are optional. FeeTokenID can be 0 (pay with ETH)
V2MorphTxVersion2 = 2Available after Celadon forkV1 fields plus EIP-7702 authorizationList. A non-empty list cannot create a contract

1.2 Key Characteristics​

  • Gas pricing model: Fully compatible with EIP-1559 — uses maxFeePerGas + maxPriorityFeePerGas
  • Signing algorithm: Standard secp256k1 ECDSA, V value is {0, 1} (same as DynamicFeeTx)
  • Chain ID binding: ChainID is included in the signing hash to prevent cross-chain replay

2. Data Structures​

2.1 Core Struct — MorphTx​

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 // Version (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
}

2.2 Dependent Types​

TypeDefined inDescription
common.Referencecommon/types.go[32]byte fixed-length array, supports Hex/JSON/GraphQL serialization
common.ReferenceLengthcommon/types.goConstant 32
common.MaxMemoLengthcommon/types.goConstant 64
AccessListcore/types/access_list_tx.go[]AccessTuple, EIP-2930 access list

2.3 Version Validation Rules​

Source: core/types/transaction.go → ValidateMorphTxVersion()

VersionFeeTokenIDFeeLimitReferenceMemoAuthListValid?
V0Must be > 0OptionalMust be nil/emptyMust be nil/emptyMust be empty✅
V0= 0----❌ ErrMorphTxV0IllegalExtraParams
V0> 0-Non-empty--❌ ErrMorphTxV0IllegalExtraParams
V0 or V1----Non-empty❌ ErrMorphTxAuthListRequiresV2
V1Anynil or 0 when FeeTokenID = 0Any≤ 64BEmpty✅
V2Anynil or 0 when FeeTokenID = 0Any≤ 64BAny, including empty✅
V1 or V2= 0> 0---❌ ErrMorphTxIllegalExtraParams
V1 or V2---> 64B-❌ ErrMemoTooLong
V2----Non-empty and to == nil❌ ErrMorphTxV2ContractCreation
Other-----❌ ErrMorphTxUnsupportedVersion

Core constraints:

  • V0 is designed specifically for Alt Fee — FeeTokenID must be non-zero
  • V1 and V2 are general-purpose — Alt Fee, Reference, and Memo are optional. If FeeTokenID == 0 (using ETH), FeeLimit must be zero/nil
  • V2 adds authorizationList. An empty list is legal. A non-empty list requires to
  • Memo max 64 bytes applies to V1 and V2

2.4 Error Types​

ErrorMeaning
ErrMorphTxV0IllegalExtraParamsV0 params invalid (FeeTokenID=0, or Reference/Memo set)
ErrMorphTxIllegalExtraParamsFeeTokenID=0 but FeeLimit>0. Applies to V1 and V2
ErrMorphTxAuthListRequiresV2authorizationList set on V0 or V1
ErrMorphTxV2ContractCreationV2 authorization list is non-empty and to is nil
ErrMorphTxUnsupportedVersionUnsupported version number
ErrMorphTxV1NotYetActiveV1 tx submitted before Jade fork activation
ErrMorphTxV2NotYetActiveV2 tx submitted before Celadon fork activation
ErrMemoTooLongMemo exceeds 64 bytes

3. Fork Timeline & Compatibility​

MorphTx requires three forks to fully enable. Timestamps 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) │ │ │

3.1 Emerald Fork​

Source: core/types/transaction_signing.go → newModernSigner() Config: params/config.go → EmeraldTime

After Emerald fork activation:

  • MorphTxType (0x7F) is registered in modernSigner's supported type list
  • MakeSigner() returns a signer that accepts MorphTx
  • Only V0 is available (V1 and V2 are rejected by tx pool and block validator)

Before Emerald fork:

  • MorphTx is rejected at the tx pool level (ErrTxTypeNotSupported)
  • EIP-1559 must already be active (MorphTx depends on the eip1559 flag)

3.2 Jade Fork​

Source: core/tx_pool.go, core/block_validator.go Config: params/config.go → JadeForkTime

After Jade fork activation:

  • V1 transactions are accepted by the tx pool
  • Block validation allows V1 transactions
  • Reference index system becomes active

Before Jade fork:

  • Tx pool rejects V1: !pool.jade && tx.IsMorphTx() && tx.Version() == MorphTxVersion1
  • Block validation rejects V1: !isJadeFork && tx.IsMorphTx() && tx.Version() == MorphTxVersion1
  • RPC setDefaults rejects V1 fields (reference / memo)

On Jade fork rollback (reorg):

  • Tx pool actively removes all V1 transactions (removeMorphTxV1())

3.3 Celadon Fork​

Config: params/config.go → CeladonTime

After Celadon fork activation:

  • V2 transactions are accepted by the tx pool and block validation
  • Alt Fee refunds add the charge-time rounding credit and round down
  • A reorg behind Celadon removes V2 transactions from the tx pool (removeMorphTxV2())

Before Celadon fork:

  • Tx pool and block validation reject V2 with ErrMorphTxV2NotYetActive
  • RPC setDefaults rejects an inferred V2

3.4 Fork Configuration​

Hoodi testnet:

{
"emeraldTime": 1766988000,
"jadeForkTime": 1774418400,
"celadonTime": 1793167200
}
ForkTimestampActivation (UTC)
Emerald17669880002025-12-29 06:00
Jade17744184002026-03-25 06:00
Celadon17931672002026-10-28 06:00

Mainnet:

{
"emeraldTime": 1767765600,
"jadeForkTime": 1775628000,
"celadonTime": 1793772000
}
ForkTimestampActivation (UTC)
Emerald17677656002026-01-07 06:00
Jade17756280002026-04-08 06:00
Celadon17937720002026-11-04 06:00

4. Encoding/Decoding (Wire Format)​

4.1 Full Wire Format​

MorphTx follows the EIP-2718 envelope format: 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 │ │
│ └────┴────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘

4.2 V0 Encoding​

Format: 0x7F || RLP([14 fields])

Field order (inside RLP list):
0. chainID (*big.Int)
1. nonce (uint64)
2. gasTipCap (*big.Int)
3. gasFeeCap (*big.Int)
4. gas (uint64)
5. to (*common.Address, nil=contract creation)
6. value (*big.Int)
7. data ([]byte)
8. accessList (AccessList)
9. feeTokenID (uint16)
10. feeLimit (*big.Int)
11. v (*big.Int)
12. r (*big.Int)
13. s (*big.Int)

Constraint: feeTokenID must be non-zero.

4.3 V1 Encoding​

Format: 0x7F || 0x01 || RLP([16 fields])

Field order (inside RLP list):
0. chainID (*big.Int)
1. nonce (uint64)
2. gasTipCap (*big.Int)
3. gasFeeCap (*big.Int)
4. gas (uint64)
5. to (*common.Address, nil=contract creation)
6. value (*big.Int)
7. data ([]byte)
8. accessList (AccessList)
9. feeTokenID (uint16)
10. feeLimit (*big.Int)
11. reference ([]byte, length 0 or 32)
12. memo ([]byte, length 0~64)
13. v (*big.Int)
14. r (*big.Int)
15. s (*big.Int)

Key details:

  • The version byte (0x01) is NOT inside the RLP list — it's a prefix byte
  • reference and memo use []byte type in RLP (not [32]byte); empty values encode as RLP empty string (0x80)
  • V1 adds reference and memo compared to V0's 14 fields (16 total)

4.4 V2 Encoding​

Format: 0x7F || 0x02 || RLP([17 fields])

Field order (inside RLP list):
0. chainID (*big.Int)
1. nonce (uint64)
2. gasTipCap (*big.Int)
3. gasFeeCap (*big.Int)
4. gas (uint64)
5. to (*common.Address, nil=contract creation)
6. value (*big.Int)
7. data ([]byte)
8. accessList (AccessList)
9. feeTokenID (uint16)
10. feeLimit (*big.Int)
11. reference ([]byte, length 0 or 32)
12. memo ([]byte, length 0~64)
13. authorizationList (EIP-7702 authorizations)
14. v (*big.Int)
15. r (*big.Int)
16. s (*big.Int)

The version byte 0x02 is a prefix, not a field inside the RLP list. An empty authorizationList is legal. A non-empty list requires to.

4.5 Version Detection Algorithm​

When decoding inner payload, the first byte determines the version:

firstByte = inner_payload[0]

if firstByte >= 0xC0 or firstByte == 0x00:
→ V0 format (first byte is RLP list prefix)
→ Decode entire payload as RLP list

elif firstByte == 0x01:
→ V1 format (first byte is version)
→ Skip 1 byte, decode remainder as RLP list

elif firstByte == 0x02:
→ V2 format (first byte is version)
→ Skip 1 byte, decode remainder as RLP list

else:
→ Unsupported version

Design rationale: V0's RLP list first byte is always >= 0xC0 (RLP list encoding prefix), while V1's first byte is 0x01 and V2's first byte is 0x02. They do not overlap.

4.6 Encoding Paths​

Two encoding paths exist, both producing identical byte output:

Path 1: Transaction.MarshalBinary()
└→ Transaction.encodeTyped(buf)
├→ buf.WriteByte(0x7F) // txType prefix
└→ MorphTx.encode(buf) // internal encoding (V0, V1, or V2)

Path 2: rlp.Encode(w, morphTx)
└→ MorphTx.EncodeRLP(w) // custom rlp.Encoder
└→ MorphTx.encode(buf) // same function as Path 1

EncodeRLP ensures that Transaction.Hash() (which internally calls rlp.Encode) produces output consistent with MarshalBinary.

4.7 Decoding Paths​

Path 1: Transaction.UnmarshalBinary(bytes)
└→ Transaction.decodeTyped(bytes)
├→ Check bytes[0] == 0x7F
├→ inner = new(MorphTx)
└→ inner.decode(bytes[1:]) // version detection + decode

Path 2: rlp.Decode(reader, &morphTx)
└→ MorphTx.DecodeRLP(stream) // custom rlp.Decoder
├→ stream.Kind() == List → V0
├→ version byte 0x01 + stream.Raw() → V1
└→ version byte 0x02 + stream.Raw() → V2

Why DecodeRLP is necessary: Go struct field order ([...AccessList, Version, FeeTokenID, ...]) doesn't match V0 wire format ([...AccessList, FeeTokenID, ...]). Reflection-based decoding would cause type overflow errors.

4.8 Transaction Hash​

V0: keccak256(0x7F || rlp.Encode(morphTx))
= keccak256(0x7F || RLP([14 fields including signature]))

V1: keccak256(0x7F || rlp.Encode(morphTx))
= keccak256(0x7F || 0x01 || RLP([16 fields including signature]))

V2: keccak256(0x7F || rlp.Encode(morphTx))
= keccak256(0x7F || 0x02 || RLP([17 fields including signature]))

Note: rlp.Encode(morphTx) calls the custom EncodeRLP, so V1 and V2 outputs include the 0x01 and 0x02 version prefix bytes.


5. Signing Mechanism​

5.1 Signer Requirements​

MorphTx must be signed with an Emerald or higher-level signer:

// Recommended
signer := types.NewEmeraldSigner(chainID)

// Or auto-selected by protocol (Emerald must be active)
signer := types.MakeSigner(config, blockNumber, blockTime)

// LatestSignerForChainID returns NewEmeraldSigner
signer := types.LatestSignerForChainID(chainID)

5.2 Signing Hash Calculation​

The signing hash is the digest used for signing/verification — it does NOT include V/R/S signature values.

V0 signing hash (11 fields):

sigHash = keccak256(0x7F || rlp([
chainID, nonce, gasTipCap, gasFeeCap, gas, to, value, data,
accessList, feeTokenID, feeLimit
]))

V1 signing hash (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 compared to V0.

V2 signing hash (15 fields):

sigHash = keccak256(0x7F || rlp([
chainID, nonce, gasTipCap, gasFeeCap, gas, to, value, data,
accessList, feeTokenID, feeLimit, version, reference, memo,
authorizationList
]))

V2 adds authorizationList. Nil reference and memo still encode as 0x80, and an empty authorization list is part of the hash. Versions after V1, including V2, use this latest signing payload; the version byte inside the payload keeps an unknown version from verifying as V2.

5.3 Signing Flow​

// 1. Construct unsigned transaction
tx := types.NewTx(&types.MorphTx{
ChainID: chainID,
Nonce: nonce,
GasTipCap: gasTipCap,
GasFeeCap: gasFeeCap,
Gas: gasLimit,
To: &toAddr,
Value: value,
Data: data,
FeeTokenID: 1,
FeeLimit: feeLimit,
Version: types.MorphTxVersion0,
})

// 2. Sign
signer := types.NewEmeraldSigner(chainID)
signedTx, err := types.SignTx(tx, signer, privateKey)

Internal flow:

types.SignTx(tx, signer, privateKey)
├→ h = signer.Hash(tx) // modernSigner.Hash
│ └→ tx.inner.sigHash(signer.chainID) // MorphTx.sigHash
│ └→ v0SigHash, v1SigHash, or v2SigHash
├→ sig = crypto.Sign(h[:], privateKey) // 65-byte signature
└→ tx.WithSignature(signer, sig)
└→ signer.SignatureValues(tx, sig)
├→ R = sig[0:32]
├→ S = sig[32:64]
└→ V = sig[64] (0 or 1)

5.4 V/R/S Specification​

  • V value: 0 or 1 (recovery identifier), same as DynamicFeeTx and other modern tx types
  • Sender recovery: V + 27 to convert to Homestead format, then call ecrecover
  • Signature encoding: Standard 65 bytes: R (32 bytes) || S (32 bytes) || V (1 byte)

6. RPC Interfaces​

6.1 Standard eth Namespace​

eth_sendTransaction​

Constructs MorphTx via TransactionArgs. Supported Morph-specific fields:

{
"from": "0x...",
"to": "0x...",
"maxFeePerGas": "0x...",
"maxPriorityFeePerGas": "0x...",
"gas": "0x...",
"value": "0x...",
"data": "0x...",
"feeTokenID": "0x1",
"feeLimit": "0x...",
"reference": "0x1234...cdef",
"memo": "0x68656c6c6f"
}

Type auto-detection: The transaction is identified as MorphTx when any of these fields are set:

  • feeTokenID > 0
  • reference is non-empty and non-zero
  • memo is non-empty

authorizationList alone selects a SetCode transaction (0x04). Combined with one of the Morph fields above, it selects MorphTx V2.

Version inference: eth_sendTransaction does not accept version.

  1. A non-empty authorizationList on a MorphTx selects V2
  2. Every other unsigned MorphTx is V1, including Alt Fee transactions that older clients built as V0
  3. Signed V0 payloads remain valid on eth_sendRawTransaction
warning

If you set both gasPrice AND MorphTx fields (e.g., feeTokenID), gasPrice will override the type detection and produce a LegacyTx instead of MorphTx, silently discarding all Morph fields. Always use maxFeePerGas/maxPriorityFeePerGas with MorphTx.

eth_sendRawTransaction​

Accepts a signed transaction in RLP-encoded type envelope format:

0x7F || inner_payload

The node automatically decodes via UnmarshalBinary → decodeTyped → MorphTx.decode.

eth_getTransactionByHash / eth_getTransactionByBlockHashAndIndex​

Returns RPCTransaction with MorphTx fields:

{
"type": "0x7f",
"chainId": "0xb02",
"nonce": "0x1",
"maxFeePerGas": "0x...",
"maxPriorityFeePerGas": "0x...",
"gas": "0x...",
"to": "0x...",
"value": "0x...",
"input": "0x...",
"accessList": [],
"feeTokenID": "0x1",
"feeLimit": "0x...",
"version": "0x1",
"reference": "0x1234...cdef",
"memo": "0x68656c6c6f",
"v": "0x0",
"r": "0x...",
"s": "0x..."
}

Note: version, reference, and memo appear for V1+ transactions (omitempty). V2 responses also include authorizationList, encoded as [] when the list is empty. V0 transactions only return feeTokenID and feeLimit.

eth_getTransactionReceipt​

Morph extension fields in the receipt:

{
"feeTokenID": "0x1",
"feeLimit": "0x...",
"feeRate": "0x...",
"tokenScale": "0x...",
"version": "0x0",
"reference": null,
"memo": null,
"l1Fee": "0x..."
}

eth_estimateGas​

Gas estimation for MorphTx additionally considers:

  • Alt Fee token balance and FeeLimit constraint
  • L1 Data Fee conversion to token units
  • Whether the token is in active state

eth_call​

Accepts Morph fields in the JSON-RPC call object for simulated execution. ethclient does not currently forward FeeTokenID / FeeLimit / Reference / Memo via toCallArg; use a raw RPC parameter when those fields matter.

6.2 morph Namespace (Public)​

morph_getTransactionHashesByReference​

Query transactions associated with a Reference, with pagination support.

Parameters:

{
"reference": "0x1234...cdef",
"offset": "0x0",
"limit": "0x64"
}

Constraints:

  • limit: max 100
  • offset: max 10000 (prevents linear scan DoS)

Returns: sorted by blockTimestamp + txIndex ascending:

[
{
"transactionHash": "0x...",
"blockNumber": "0x123",
"blockTimestamp": "0x...",
"transactionIndex": "0x0"
}
]

6.3 morph Namespace (Private/Internal)​

morph_estimateL1DataFee​

Estimates L1 data fee for a transaction. Input is TransactionArgs — Morph fields affect the serialized transaction size and thus the L1 fee.


7. Go SDK Development Guide​

7.1 Using ethclient​

client, _ := ethclient.Dial("http://localhost:8545")

// Query transactions by Reference
results, err := client.GetTransactionHashesByReference(ctx,
common.HexToReference("0x1234..."),
nil, // offset, default 0
nil, // limit, default 100
)

7.2 Using Contract Bindings (accounts/abi/bind)​

Source: accounts/abi/bind/base.go

Morph fields in TransactOpts:

type TransactOpts struct {
// ... standard fields ...
FeeTokenID uint16
FeeLimit *big.Int
Reference *common.Reference
Memo *[]byte
AuthorizationList []types.SetCodeAuthorization
}

Usage example:

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

Version derivation (morphTxVersion):

non-empty AuthorizationList → V2
otherwise MorphTx → V1

TransactOpts does not accept an explicit version. A non-empty authorization list with no Morph field (FeeTokenID, Reference, or Memo) builds a SetCode transaction instead of MorphTx.

Transaction type auto-selection: When FeeTokenID != 0 or Reference/Memo is set, BoundContract.transact() calls createMorphTx().

7.3 Direct Transaction Construction​

// V0 Example: Pay gas with token ID=1
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,
FeeLimit: big.NewInt(5e17),
Version: types.MorphTxVersion0,
})

// V1 Example: Pay with ETH + attach Reference and Memo
ref := common.HexToReference("0xabcd...")
memo := []byte("hello morph")
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,
Memo: &memo,
})

// V2 Example: Pay gas with token ID=1 + Reference + EIP-7702 AuthorizationList
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,
FeeLimit: big.NewInt(5e17),
Version: types.MorphTxVersion2,
Reference: &ref,
Memo: &memo,
AuthList: []types.SetCodeAuthorization{signedAuth},
})

// Sign
signer := types.NewEmeraldSigner(big.NewInt(2818))
signedTx, _ := types.SignTx(tx, signer, privateKey)

// Serialize (for sending raw transaction)
rawBytes, _ := signedTx.MarshalBinary()

7.4 Using CallMsg​

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),
}

ethclient.toCallArg currently forwards only authorizationList among Morph-adjacent fields. It does not send FeeTokenID, FeeLimit, Reference, or Memo, so client.EstimateGas(ctx, msg) with those fields set will not produce an Alt Fee estimate. Pass the same shape as a raw eth_estimateGas JSON-RPC parameter instead. The node does not accept a version field on estimate requests; it infers V1 from feeTokenID (or V2 when a non-empty authorizationList is present with Morph fields).


8. Other Language SDK Guide​

8.1 Transaction Type Identifier​

  • EIP-2718 type byte: 0x7F (127)
  • This is a typed transaction following the standard envelope format

8.2 Encoding Implementation​

V0 Encoding​

raw_bytes = [0x7F] + rlp_encode([
chain_id, # big integer
nonce, # uint64
max_priority_fee, # big integer (gasTipCap)
max_fee, # big integer (gasFeeCap)
gas_limit, # uint64
to, # 20 bytes or empty (contract creation)
value, # big integer
data, # bytes
access_list, # [[address, [storage_keys]], ...]
fee_token_id, # uint16 (MUST be > 0)
fee_limit, # big integer
v, # big integer (0 or 1)
r, # big integer
s, # big integer
])

V1 Encoding​

raw_bytes = [0x7F, 0x01] + rlp_encode([
chain_id,
nonce,
max_priority_fee,
max_fee,
gas_limit,
to,
value,
data,
access_list,
fee_token_id, # uint16 (can be 0)
fee_limit, # big integer
reference, # bytes (0 or 32 bytes)
memo, # bytes (0~64 bytes)
v,
r,
s,
])

V2 Encoding​

raw_bytes = [0x7F, 0x02] + rlp_encode([
chain_id,
nonce,
max_priority_fee,
max_fee,
gas_limit,
to,
value,
data,
access_list,
fee_token_id,
fee_limit,
reference,
memo,
authorization_list,
v,
r,
s,
])

8.3 Signing Implementation​

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
])
)

Key differences:

  • V0 signing hash does not include version/reference/memo
  • V1 signing hash includes version (value=1), reference (pointer may be nil), memo (pointer may be nil)
  • V2 signing hash adds authorization_list, including when the list is empty
  • In Go, nil pointers encode as RLP empty string (0x80) — other language SDKs must handle this correctly

Signing & Recovery​

  • Use standard secp256k1 ECDSA to sign the sig_hash
  • V value is the recovery identifier: 0 or 1 (NOT 27/28)
  • To recover the sender address, add 27 to V and use ecrecover

8.4 Decoding Implementation​

# Pseudocode

def decode_morph_tx(raw_bytes):
assert raw_bytes[0] == 0x7F # type byte
payload = raw_bytes[1:]

first_byte = payload[0]
if first_byte >= 0xC0 or first_byte == 0x00:
# V0: direct RLP decode
fields = rlp_decode(payload) # 14 fields
assert fields[9] > 0 # feeTokenID must be non-zero
return MorphTxV0(fields)

elif first_byte == 0x01:
# V1: skip version byte
fields = rlp_decode(payload[1:]) # 16 fields
reference = fields[11] # 0 or 32 bytes
memo = fields[12] # 0~64 bytes
return MorphTxV1(fields)

elif first_byte == 0x02:
# V2: skip version byte
fields = rlp_decode(payload[1:]) # 17 fields
return MorphTxV2(fields)

else:
raise Error("unsupported version")

8.5 JSON-RPC Field Mapping​

Go FieldJSON FieldTypeDescription
GasTipCapmaxPriorityFeePerGashex big intEIP-1559 priority fee
GasFeeCapmaxFeePerGashex big intEIP-1559 fee cap
FeeTokenIDfeeTokenIDhex uint16Token ID
FeeLimitfeeLimithex big intToken fee cap
Versionversionhex uint64Response only, V1+ (omitempty). Not an eth_sendTransaction input
Referencereferencehex bytes32Reference key (V1+ only)
Memomemohex bytesMemo (V1+ only)
AuthListauthorizationListauthorization arrayV2 only. Empty list encodes as []

Note on version:

  • TransactionArgs (sending) does not include version. The node infers V1, or V2 when authorizationList is non-empty
  • RPCTransaction and txJSON return version as hexutil.Uint64 for V1+

9. Alt Fee Mechanism​

9.1 Concept​

Alt Fee allows users to pay transaction gas fees using on-chain registered ERC-20 tokens (e.g., USDT, USDC) instead of ETH. Unlike Paymaster-based models that require extra contract calls and external bundlers, Alt Fee is handled directly at the protocol level, reducing overhead and improving efficiency.

9.2 Key Fields​

FieldTypeDescription
FeeTokenIDuint16Token's on-chain registry ID (0 = ETH, > 0 = token)
FeeLimit*big.IntMaximum token amount the user is willing to pay

9.3 Fee Conversion​

The system follows EIP-1559 to calculate fees in ETH, then converts to the selected token using an on-chain oracle rate:

tokenAmount = ⌈(ethAmount × tokenScale) / tokenRate⌉

Ceiling rounding ensures the token amount always fully covers the ETH fee. Before Celadon, unused gas is refunded with the same ceiling. From Celadon onward the charge still rounds up and records roundingCredit; the refund is ⌊(remaining × tokenScale + roundingCredit) / tokenRate⌋. This applies to every Alt Fee transaction.

Token rates are maintained by oracle services and stored in the Token Registry system contract at:

0x5300000000000000000000000000000000000021

9.4 Constraint Rules​

  1. V0 must use Alt Fee: FeeTokenID > 0
  2. V1 and V2 Alt Fee is optional: FeeTokenID can be 0 (use ETH)
  3. FeeLimit is linked to FeeTokenID: If FeeTokenID == 0, then FeeLimit must be nil/0
  4. Token must be active: Tx pool and execution check whether the token is in active state

9.5 Alt Fee in Gas Estimation​

When using eth_estimateGas:

  • If FeeTokenID is set, the node queries the user's token balance instead of ETH balance
  • L1 Data Fee is converted to token units at the current exchange rate
  • FeeLimit participates in the payable gas cap calculation

9.6 Fee Info in Receipts​

After execution, the receipt contains:

  • feeRate: ETH/token exchange rate used at execution time
  • tokenScale: Exchange rate precision scale
  • l1Fee: L1 data fee

10. Reference Index System​

10.1 Concept​

Reference is a 32-byte on-chain index key that allows users to associate multiple transactions with the same identifier, queryable via RPC.

10.2 Storage Mechanism​

Source: core/rawdb/accessors_reference_index.go

  • Write timing: When a block is successfully inserted into the chain (core/blockchain.go → maintainReferenceIndex)
  • Index key format: prefix + reference(32B) + blockTimestamp(8B) + txIndex(8B) + txHash(32B)
  • Value: Empty (leverages key ordering for range queries)
  • Sort order: Naturally ascending by blockTimestamp + txIndex

10.3 Querying​

Use morph_getTransactionHashesByReference RPC (see Section 6.2).

10.4 Use Cases​

  • Order systems: Hash an order ID as Reference, query all related transactions
  • Batch operations: Use a batch identifier as Reference, track all transactions in a batch
  • Cross-system correlation: Map external system IDs to References

10.5 Important Notes​

  • Reference is available in V1 and V2 MorphTx
  • Reference indexing begins after the Jade fork
  • The same Reference can be used by multiple transactions
  • Index auto-updates with chain reorgs (written on insertion, deleted on rollback)

11. Receipt Extensions​

Source: core/state_processor.go, core/types/receipt.go

MorphTx receipts include these extension fields:

FieldTypeConditionDescription
FeeTokenID*uint16All MorphTxToken ID used (0 = ETH)
FeeLimit*big.IntAll MorphTxToken fee cap (may be nil)
FeeRate*big.IntAlt Fee only (feeTokenID > 0)ETH/token exchange rate at execution
TokenScale*big.IntAlt Fee only (feeTokenID > 0)Exchange rate precision scale
L1Fee*big.IntAll MorphTxL1 data fee
Versionuint8V1+ onlyTransaction version
Reference*common.ReferenceV1+ onlyReference key
Memo*[]byteV1+ onlyMemo

12. Common Pitfalls​

Pitfall 1: gasPrice Overrides MorphTx Type Detection​

Problem: In eth_sendTransaction params, if you set both gasPrice AND MorphTx fields (e.g., feeTokenID), gasPrice overrides the final type to LegacyTxType, silently discarding all Morph fields.

// internal/ethapi/transaction_args.go → toTransaction()
usedType := types.LegacyTxType
switch {
case ..MorphTx conditions..:
usedType = types.MorphTxType // ① First identified as MorphTx
...
}
if args.GasPrice != nil {
usedType = types.LegacyTxType // ② But gasPrice overrides!
}

Solution: Always use maxFeePerGas and maxPriorityFeePerGas with MorphTx. Never set gasPrice.

Pitfall 2: V0 vs Later FeeTokenID Semantics​

V0V1 and V2
FeeTokenID == 0❌ Invalid✅ Valid (means use ETH)
PurposeAlt Fee onlyGeneral-purpose MorphTx, Alt Fee optional

If migrating from V0 to V1 or V2, FeeTokenID is no longer required. eth_sendTransaction now builds those Alt Fee transactions as V1 unless an authorization list selects V2.

Pitfall 3: V1 and V2 Signing Hashes Include nil Pointer RLP Encoding​

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 SDK implementations must handle this correctly.

Pitfall 4: Submitting V1 Transactions Before Jade Fork​

Before Jade fork activation:

  • eth_sendTransaction's setDefaults will directly reject
  • eth_sendRawTransaction will be rejected at tx pool entry
  • Even if you can construct a V1 transaction, block validation will reject it

Pitfall 5: RPC version Field Only Appears for V1+​

V0 transactions' RPCTransaction does NOT include version, reference, memo, or authorizationList fields (omitempty). SDKs must handle missing fields:

  • If version is missing → default to V0
  • If reference is missing → nil
  • If memo is missing → nil
  • authorizationList only appears on V2 responses (encoded as [] when empty)

Pitfall 6: V0 Encoding Rejects FeeTokenID == 0​

V0 format validates FeeTokenID != 0 at both encoding and decoding time:

  • You cannot construct a V0 transaction with FeeTokenID == 0
  • If you receive a transaction claiming to be V0 but with FeeTokenID == 0, decoding will fail

Pitfall 7: Submitting V2 Transactions Before the Celadon Fork​

Before Celadon fork activation:

  • eth_sendTransaction, eth_sendRawTransaction, the tx pool, and block validation all reject V2 with ErrMorphTxV2NotYetActive
  • A reorg behind the Celadon boundary removes V2 transactions from the tx pool (removeMorphTxV2())

13. Appendix: Full Call Path Diagrams​

13.1 Send Transaction (eth_sendTransaction)​

User JSON-RPC request
│
▼
PublicTransactionPoolAPI.SendTransaction()
│
├→ args.setDefaults(ctx, backend)
│ ├→ Fill maxFeePerGas / maxPriorityFeePerGas (EIP-1559)
│ ├→ Fill nonce
│ ├→ isMorphTxArgs() → true?
│ │ ├→ Infer version (V1, or V2 when authorizationList is non-empty)
│ │ ├→ Check Jade fork status (V1) and Celadon fork status (V2)
│ │ └→ validateMorphTxVersion()
│ ├→ Validate memo length
│ └→ DoEstimateGas() → estimate gas (with Alt Fee logic)
│
├→ args.toTransaction()
│ └→ Construct types.MorphTx{...}
│ └→ types.NewTx(data)
│
├→ wallet.SignTx(account, tx, chainID)
│ └→ keystore.SignTx()
│ └→ types.SignTx(tx, LatestSignerForChainID(chainID), key)
│ └→ NewEmeraldSigner → modernSigner.Hash → MorphTx.sigHash
│
└→ SubmitTransaction()
└→ backend.SendTx() → enters tx pool
└→ TxPool.validateTx()
├→ Check eip1559 active
├→ Check Jade fork (V1) and Celadon fork (V2)
├→ ValidateMorphTxVersion()
├→ Check token active (Alt Fee)
└→ Check balance (ETH or token)

13.2 Send Raw Transaction (eth_sendRawTransaction)​

User submits raw bytes (0x7F || inner_payload)
│
▼
PublicTransactionPoolAPI.SendRawTransaction()
│
├→ tx.UnmarshalBinary(rawBytes)
│ └→ decodeTyped(rawBytes)
│ ├→ rawBytes[0] == 0x7F → inner = new(MorphTx)
│ └→ inner.decode(rawBytes[1:])
│ ├→ First byte version detection
│ ├→ V0: decodeV0MorphTxRLP()
│ ├→ V1: decodeV1MorphTxRLP()
│ └→ V2: decodeV2MorphTxRLP()
│
└→ SubmitTransaction()
└→ (same as above)

13.3 Query Transaction​

eth_getTransactionByHash
│
▼
NewRPCTransaction(tx, ...)
├→ types.Sender(signer, tx) → recover sender
├→ tx.RawSignatureValues() → V, R, S
├→ case types.MorphTxType:
│ ├→ Fill accessList, chainID, gasFeeCap, gasTipCap
│ ├→ Fill feeTokenID, feeLimit
│ └→ if tx.Version() >= V1:
│ ├→ Fill version, reference, memo
│ └→ if tx.Version() == V2:
│ └→ Fill authorizationList
└→ Return RPCTransaction JSON

13.4 Block Validation​

BlockValidator.ValidateBody(block)
│
├→ isJadeFork = config.IsJadeFork(block.Time())
├→ isCeladon = config.IsCeladon(block.Time())
│
└→ for tx in block.Transactions():
├→ if !isJadeFork && tx.IsMorphTx() && tx.Version() == V1:
│ └→ return ErrMorphTxV1NotYetActive
├→ if !isCeladon && tx.IsMorphTx() && tx.Version() == V2:
│ └→ return ErrMorphTxV2NotYetActive
└→ tx.ValidateMorphTxVersion()
└→ Check version/field validity

13.5 Execution & Receipt Generation​

StateProcessor.applyTransaction(tx)
│
├→ tx.AsMessage(signer, baseFee)
│ ├→ ValidateMorphTxVersion()
│ └→ Construct Message{feeTokenID, version, reference, memo, setCodeAuthorizations, ...}
│
├→ ApplyMessage(evm, msg, gasPool)
│ └→ StateTransition.Execute()
│ ├→ buyGas() → if Alt Fee, query token balance & rate
│ ├→ Apply EIP-7702 authorizations (if non-empty)
│ ├→ EVM execution
│ └→ refundGas() → refund unused gas (ETH or token; floor + roundingCredit from Celadon)
│
└→ Build Receipt
├→ receipt.FeeTokenID = tx.FeeTokenID()
├→ receipt.FeeLimit = tx.FeeLimit()
├→ receipt.FeeRate = result.FeeRate
├→ receipt.TokenScale = result.TokenScale
├→ receipt.L1Fee = result.L1DataFee
└→ if tx.Version() >= V1:
├→ receipt.Version = tx.Version()
├→ receipt.Reference = tx.Reference()
└→ receipt.Memo = tx.Memo()

Appendix B: Source File Index​

File PathResponsibility
core/types/morph_tx.goMorphTx struct, encoding/decoding, signing hash
core/types/transaction.goTxData interface, type constant (0x7F), version validation, AsMessage
core/types/transaction_signing.goSigner interface, modernSigner, SignTx, NewEmeraldSigner
core/types/transaction_marshalling.goJSON serialization/deserialization
core/types/receipt.goReceipt struct and Morph extension fields
core/types/hashing.goprefixedRlpHash
internal/ethapi/transaction_args.goRPC param handling, version inference, validation
internal/ethapi/api.goRPCTransaction, SendTransaction, Receipt serialization, PublicMorphAPI
internal/ethapi/backend.gomorph namespace registration
core/tx_pool.goTx pool validation, Jade/Celadon fork checks, V1/V2 cleanup
core/block_validator.goBlock validation MorphTx checks
core/state_processor.goPost-execution receipt population
core/state_transition.goAlt Fee deduction and refund logic
core/blockchain.goReference index maintenance
core/rawdb/accessors_reference_index.goReference index read/write
accounts/abi/bind/base.goContract binding TransactOpts and createMorphTx
accounts/external/backend.goExternal signer MorphTx field passing
signer/core/apitypes/types.goClef signer SendTxArgs.ToTransaction
ethclient/ethclient.goGo client wrapper
rpc/types.goReferenceQueryArgs / ReferenceTransactionResult
rollup/fees/rollup_fee.goL1 data fee calculation with MorphTx serialization
params/config.goEmeraldTime, JadeForkTime, CeladonTime configuration
common/types.goReference type, MaxMemoLength
interfaces.goCallMsg Morph fields