Asking Claude about OP_RETURN in Bitcoin Knots

average_gary

7. Oktober 2025October 7, 2025 · 12 Min. Lesezeit12 min read

can you find all references to OP_RETURN data and outline how it's is handled. When is it serialized/deserialized and in what context? output into a markdown document

⏺ I'll search for all references to OP_RETURN in the codebase and document how it's handled, including serialization/deserialization contexts.

⏺ Search(pattern: "OP_RETURN") ⎿  Found 78 files (ctrl+o to expand)

⏺ Search(pattern: "OP_RETURN", output_mode: "content") ⎿  Found 1355 lines (ctrl+o to expand)

⏺ Read(src/script/script.h) ⎿  Read 631 lines (ctrl+o to expand)

⏺ Read(src/script/solver.cpp) ⎿  Read 239 lines (ctrl+o to expand)

⏺ Read(src/script/interpreter.cpp) ⎿  Error: File content (27421 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.

⏺ Read(src/policy/policy.cpp) ⎿  Read 492 lines (ctrl+o to expand)

⏺ Read(src/compressor.h) ⎿  Read 119 lines (ctrl+o to expand)

⏺ Read(src/core_write.cpp) ⎿  Read 277 lines (ctrl+o to expand)

⏺ Read(src/blockfilter.cpp) ⎿  Read 284 lines (ctrl+o to expand)

⏺ Read(src/script/script.cpp) ⎿  Read 440 lines (ctrl+o to expand)

⏺ Search(pattern: "IsUnspendable", output_mode: "content") ⎿  Found 122 lines (ctrl+o to expand)

⏺ Read(src/script/interpreter.cpp) ⎿  Read 200 lines (ctrl+o to expand)

⏺ Write(OP_RETURN_ANALYSIS.md) ⎿  Wrote 549 lines to OP_RETURN_ANALYSIS.md # OP_RETURN Data Handling Analysis ## Overview This document outlines how OP_RETURN data is handled throughout the Bitcoin Knots codebase, including where it's serialized/deserialized and the contexts in which it operates. ## What is OP_RETURN? OP_RETURN is a Bitcoin script opcode (0x6a) that marks transaction outputs as provably unspendable. It's commonly used for embedding arbitrary data in the blockchain. … +539 lines (ctrl+o to expand)

⏺ Created comprehensive documentation in OP_RETURN_ANALYSIS.md covering:

Serialization/Deserialization Contexts:

  1. Standard Script Serialization - Binary format in transactions/blocks via SERIALIZE_METHODS (src/script/script.h:438)
  2. Script Compression (UTXO DB) - Uses ScriptCompression wrapper, but OP_RETURN outputs are excluded from UTXO set entirely (src/compressor.h:54-96)
  3. Witness Commitments - SegWit uses OP_RETURN for coinbase commitments (src/validation.cpp:4324-4330)
  4. Block Filters - OP_RETURN explicitly excluded from BIP 157/158 filters (src/blockfilter.cpp:197)
  5. RPC/JSON - Decoded via ScriptToAsmStr() and displayed as "nulldata" type (src/core_write.cpp)

Key Handling Points:

The document includes code references, data flow diagrams, configuration examples, and security considerations.

OP_RETURN Data Handling Analysis

Overview#

This document outlines how OP_RETURN data is handled throughout the Bitcoin Knots codebase, including where it's serialized/deserialized and the contexts in which it operates.

What is OP_RETURN?#

OP_RETURN is a Bitcoin script opcode (0x6a) that marks transaction outputs as provably unspendable. It's commonly used for embedding arbitrary data in the blockchain.

Opcode Definition: src/script/script.h:110

OP_RETURN = 0x6a,

Key Constants#

Maximum Size Limits#

Core Script Operations#

1. Script Definition and Opcodes#

Location: src/script/script.h and src/script/script.cpp

The OP_RETURN opcode is defined as part of the script language:

OP_RETURN = 0x6a,  // Control opcode

GetOpName() (src/script/script.cpp:56): Converts the opcode to string representation "OP_RETURN" for debugging/display.

2. Unspendability Detection#

Location: src/script/script.h:560-563

bool IsUnspendable() const
{
    return (size() > 0 && *begin() == OP_RETURN) || (size() > MAX_SCRIPT_SIZE);
}

This is the primary method to detect OP_RETURN outputs. Scripts starting with OP_RETURN are immediately flagged as unspendable.

Used By:

3. Script Type Identification#

Location: src/script/solver.cpp:185-187

// Provably prunable, data-carrying output
if (scriptPubKey.size() >= 1 &&
    scriptPubKey[0] == OP_RETURN &&
    scriptPubKey.IsPushOnly(scriptPubKey.begin()+1)) {
    return TxoutType::NULL_DATA;
}

Identifies OP_RETURN outputs as TxoutType::NULL_DATA. The script must:

  1. Start with OP_RETURN
  2. Have only push operations after OP_RETURN (data only, no executable code)

Type Name: Returns "nulldata" via GetTxnOutputType() (src/script/solver.cpp:26)

4. Data Carrier Byte Counting#

Location: src/script/script.cpp:306-354

The DatacarrierBytes() method analyzes scripts to count data bytes:

std::pair<size_t, size_t> CScript::DatacarrierBytes() const

Returns: {unconditional_bytes, conditional_bytes}

For OP_RETURN (src/script/script.cpp:325-328):

if (opcode == OP_RETURN && !inside_conditional) {
    // unconditional OP_RETURN is unspendable
    return {size(), 0};  // All bytes counted as unconditional data
}

When OP_RETURN is encountered outside conditionals, the entire script is considered data.

Also Tracks:

Serialization/Deserialization#

1. Standard Script Serialization#

Location: src/script/script.h:438

SERIALIZE_METHODS(CScript, obj) {
    READWRITE(AsBase<CScriptBase>(obj));
}

OP_RETURN scripts are serialized like any other script:

Contexts:

2. Script Compression (UTXO Database)#

Location: src/compressor.h:54-96

struct ScriptCompression
{
    void Ser(Stream &s, const CScript& script);
    void Unser(Stream &s, CScript& script);
}

Special Handling (src/compressor.h:87-90):

if (nSize > MAX_SCRIPT_SIZE) {
    // Overly long script, replace with a short invalid one
    script << OP_RETURN;
    s.ignore(nSize);
}

When deserializing invalid/oversized scripts, they're replaced with a single OP_RETURN byte to maintain unspendability.

Compression Scheme:

3. Witness Commitment (SegWit)#

Location: src/validation.cpp:4324-4330

CTxOut out;
out.nValue = 0;
out.scriptPubKey.resize(MINIMUM_WITNESS_COMMITMENT);
out.scriptPubKey[0] = OP_RETURN;
out.scriptPubKey[1] = 0x24;
out.scriptPubKey[2] = 0xaa;
out.scriptPubKey[3] = 0x21;
// ... witness commitment hash follows

SegWit blocks use OP_RETURN in the coinbase transaction to commit to the witness merkle tree. Format:

OP_RETURN <0x24> <0xaa21a9ed> <32-byte commitment>

4. Block Filters (BIP 157/158)#

Location: src/blockfilter.cpp:187-206

for (const CTxOut& txout : tx->vout) {
    const CScript& script = txout.scriptPubKey;
    if (script.empty() || script[0] == OP_RETURN) continue;
    // ... add to filter
}

OP_RETURN outputs are explicitly excluded from compact block filters. This:

Transaction Policy & Validation#

1. Standard Transaction Rules#

Location: src/policy/policy.cpp:79-101

bool IsStandard(const CScript& scriptPubKey,
                const std::optional<unsigned>& max_datacarrier_bytes,
                TxoutType& whichType)
{
    // ...
    if (whichType == TxoutType::NULL_DATA) {
        if (!max_datacarrier_bytes || scriptPubKey.size() > *max_datacarrier_bytes) {
            return false;
        }
    }
    return true;
}

Standardness Checks:

2. Multiple OP_RETURN Policy#

Location: src/policy/policy.cpp:190-193

// only one OP_RETURN txout is permitted
if (nDataOut > 1) {
    MaybeReject("multi-op-return");
}

Standard transactions allow only ONE OP_RETURN output per transaction. This prevents spam and maintains relay policy.

3. Token/Runes Filtering#

Location: src/policy/policy.cpp:173-176

if (whichType == TxoutType::NULL_DATA) {
    if (txout.scriptPubKey.size() > 2 &&
        txout.scriptPubKey[1] == OP_13 &&
        opts.reject_tokens) {
        MaybeReject("tokens-runes");
    }
}

Bitcoin Knots includes additional filtering for Runes protocol (identified by OP_RETURN OP_13 ...).

4. Configuration Options#

Location: src/node/mempool_args.cpp and src/kernel/mempool_options.h:72

std::optional<unsigned> max_datacarrier_bytes{
    DEFAULT_ACCEPT_DATACARRIER ?
    std::optional{MAX_OP_RETURN_RELAY} :
    std::nullopt
};

Command-line Options:

Consensus vs Policy#

Consensus Rules#

Policy Rules (Relay/Mempool)#

UTXO Set Handling#

Location: src/coins.cpp:70-74

void CCoinsViewCache::AddCoin(const COutPoint &outpoint, Coin&& coin,
                               bool possible_overwrite) {
    assert(!coin.IsSpent());
    if (coin.out.scriptPubKey.IsUnspendable()) return;  // OP_RETURN exits here
    // ... add to UTXO set
}

Critical Optimization: OP_RETURN outputs are NEVER added to the UTXO set. This:

Script Execution#

Interpreter Behavior#

Location: src/script/interpreter.cpp

When script execution encounters OP_RETURN:

  1. Immediately fails - Returns false
  2. Does not process further opcodes - Script terminates
  3. Error: SCRIPT_ERR_OP_RETURN

Defined In: src/script/script_error.h and src/script/script_error.cpp

This makes OP_RETURN outputs provably unspendable - there's no input script that can successfully spend them.

RPC and User Interface#

1. Script Decoding#

Location: src/core_write.cpp:104-147

std::string ScriptToAsmStr(const CScript& script,
                           const bool fAttemptSighashDecode)
{
    // ...
    // the IsUnspendable check makes sure not to try to decode
    // OP_RETURN data that may match the format of a signature
    if (fAttemptSighashDecode && !script.IsUnspendable()) {
        // ... signature decoding
    }
    // ...
}

When displaying scripts, OP_RETURN data is shown as hex without attempting to decode as signatures.

Example Output:

OP_RETURN 48656c6c6f20576f726c64  // "Hello World"

2. Transaction JSON Representation#

Location: src/core_write.cpp:156-175

void ScriptToUniv(const CScript& script, UniValue& out,
                  bool include_hex, bool include_address,
                  const SigningProvider* provider)
{
    out.pushKV("asm", ScriptToAsmStr(script));
    // ...
    out.pushKV("type", GetTxnOutputType(type));  // Returns "nulldata"
}

OP_RETURN outputs appear in JSON with:

3. Test Data#

Location: test/functional/data/rpc_decodescript.json:39-45

[
    "6a00",
    {
        "asm": "OP_RETURN 0",
        "desc": "raw(6a00)#ncfmkl43",
        "type": "nulldata"
    }
]

Testing#

Functional Tests#

Key Test Files:

Test Coverage Includes:

Unit Tests#

Key Files:

Data Flow Summary#

Creating a Transaction with OP_RETURN#

  1. Construction:

    CScript script;
script << OP_RETURN << data_vector;

  2. Standardness Check: IsStandard() validates size and format

  3. Policy Check: IsStandardTx() ensures only one OP_RETURN output

  4. Serialization: Standard transaction serialization (binary)

  5. Relay: Propagated if passes policy checks

  6. Block Inclusion: Miner includes in block (consensus-valid)

Processing a Block with OP_RETURN#

  1. Deserialization: Transaction decoded from block data

  2. Consensus Validation: Output is valid (any size)

  3. UTXO Update: AddCoin() skips OP_RETURN outputs via IsUnspendable() check

  4. Coin Stats: Tracked as total_unspendables_scripts

  5. Block Filter: Excluded from compact block filters

Querying OP_RETURN Data#

  1. Block Explorer: Reads from block data (not UTXO set)

  2. RPC: getrawtransaction, decoderawtransaction decode and display

  3. Format: Displayed as type: "nulldata" with hex-encoded data

Special Cases and Edge Cases#

1. Witness Commitments#

2. Invalid/Oversized Scripts#

3. Reorg Handling#

4. Conditional OP_RETURN#

OP_FALSE OP_IF OP_RETURN OP_ENDIF

Security Considerations#

1. Spam Prevention#

2. Data Injection Attacks#

3. Token Protocol Filtering#

4. UTXO Bloat#

Performance Implications#

Benefits of OP_RETURN#

  1. Fast Validation: IsUnspendable() is single byte check
  2. No UTXO Growth: Excluded from UTXO set
  3. Provable Pruning: Can be safely deleted after validation
  4. Simple Detection: First byte comparison

Costs#

  1. Blockchain Size: Data stored forever in blocks
  2. Bandwidth: Relayed to all nodes
  3. Validation Time: Must process (though fast)

Configuration Examples#

Allow OP_RETURN (Default)#

bitcoind -datacarrier=1 -datacarriersize=42

Disable OP_RETURN#

bitcoind -datacarrier=0

Custom Size Limit#

bitcoind -datacarrier=1 -datacarriersize=80

Reject Runes Tokens#

bitcoind -rejecttokens=1

Summary#

OP_RETURN is handled throughout Bitcoin Knots as follows:

Serialization: Standard binary script serialization in transactions/blocks

Deserialization: Parsed as opcode 0x6a followed by optional data

Detection: IsUnspendable() checks first byte == OP_RETURN

UTXO: Never stored in UTXO set - excluded at coin addition

Policy: Size-limited (42 bytes default), one per transaction, configurable

Consensus: Always valid, any size, provably unspendable

Execution: Script immediately fails with SCRIPT_ERR_OP_RETURN

Block Filters: Explicitly excluded from BIP 157/158 filters

Use Cases: Data anchoring, commitments, timestamping, SegWit commitments

The key insight is that OP_RETURN provides a standardized, efficient, and provably unspendable way to embed data in Bitcoin transactions while minimizing impact on the UTXO set and validation performance.

Written by

average_gary

✝️ https://farming-gods-way.org/ CPOBV Testnet4 interactive faucet. Chief Cryptologic Technician (Interpretive) Be peaceful, not harmless. (former) https://dcbitdevs.com <- Socratic Seminar https://virginiafreedom.tech…

Comments

No comments yet. Start the conversation.

Contents

17 sections

  1. Overview
  2. What is OP_RETURN?
  3. Key Constants
  4. Core Script Operations
  5. Serialization/Deserialization
  6. Transaction Policy & Validation
  7. Consensus vs Policy
  8. UTXO Set Handling
  9. Script Execution
  10. RPC and User Interface
  11. Testing
  12. Data Flow Summary
  13. Special Cases and Edge Cases
  14. Security Considerations
  15. Performance Implications
  16. Configuration Examples
  17. Summary