How to put custom messages into Bitcoin blockchain – OP_RETURN

I have spent last few days looking very closely at OP_RETURN features. This blogpost summarizes my findings and thoughts.

Bitcoin transactions – recap

Every bitcoin transaction creates outputs (called transaction outputs, sometimes called txout) from one or more transaction inputs. All except one type of these transaction output types will create spendable outputs (called unspent transaction outputs – UTXO), the type that behaves differently is OP_RETURN
The UTXO are tracked and stored by every full node (btcd or bitcoin-core/satoshi client). You can say, that transactions consume inputs and create new outputs. One transaction can contain one or more inputs and one or more outputs.

Transaction outputs have 2 parts:
– value – how much money you are sending
– a locking script – this can be understand as a set of conditions that allow you to “spend” this output. For example this can be an ownership of a specific private key.

Historical context

There were multiple attempts to store custom messages in blockchain, one very popular was to just to send coins to “meaningful address” (also called “vanity” addresses), for example to 1TodayIsFridayatpoGgzqxD7r2BMLr9dG – these addresses were incorrect, meaning that no one was able to spend coins there.
It was also possible to create CHECKMULTISIG transactions which have similar implications.
Almost all of those attempts resulted in a “blockchain bloat” – all UTXOs are stored in memory in satoshi client forever!
Moreover, in most cases the coins used to “write messages” were destroyed.
Bitcoin version 0.9 introduced new operator OP_RETURN which addresses those problems.

What is OP_RETURN?

OP_RETURN is a custom transaction locking script that can store data, but nothing beyond that, the execution of the script will be terminated immediately when bitcoin nodes encounter UTXOs that contain it – this means that you won’t be able to spend that transaction output.
When using OP_RETURN properly you will also avoid destroying coins.


OP_RETURN scripts are limited to 40 bytes, this is enough for a SHA-256 checksum (32 bytes) with 8 bytes of prefix or for a shortened URL
There can be only one OP_RETURN per transaction
OP_RETURNs are stored in blockchain, but they are not UTXOs so they will consume disk space but not RAM.

Current status – bitcoin-core/satoshi client

Bitcoin-core, currently handles OP_RETURN without any problems.
An OP_RETURN is a standard transaction, this means it’s safe to use them and all mines will process those transactions.
It only differs in one case – OP_RETURNs won’t be treated as dust in any case
Transactions that transfer 0 coins are allowed – verification
This if statement is the one that confirms that OP_RETURN won’t be dust ever – OP_RETURN is a type TX_NULL_DATA in the bitcoin core client.
Not treating OP_RETURN as dust provides a way to send transaction that transfers 0 BTC (but will require fee) – this means that coins won’t be destroyed, but relayed to the miner that will verify that transaction.

Use cases

Multiple use cases exist, these are few examples:
Proving existence of some file:
Transferring other types of assets than monetary value, for example assets:
Colored coins:

How to spot OP_RETURN transactions in blockchain

These are few examples, both on main network and on testnet (try to decode them using hex editor):

More examples can be viewed using this explorer:

How to send “blockchain messages”

At the moment it’s quite complicated to do so. You should consult following sources:
– PHP –
– Python – consult for examples
– Services – for example “Proof of existence”
– Java/bitcoinj – consult this bitcoinj group thread

More user friendly way to send OP_RETURN is coming soon to bitcoinj

How to setup a Bitcoin node

This tutorial describes how to setup a new Bitcoin node on Linux server – this node will be used as relay node in the Bitcoin network and it’s not recommended to store anything in it’s wallet.

  • Download bitcoin from official website:
  • At the moment the most recent version can be downloaded using this direct link:”>
  • Extract archive:

Create bitcoin configuration file:

Create new file in ~/.bitcoin called bitcoin.conf with following contents (you should setup different password):

Start bitcoin daemon

From this moment initial node bootstrapping begins – you’ll see a lot of server resources being used, especially disk and CPU

After few moments you can check if your node is downloading blocks from the network (bootstrapping), use this command:

You should see similar output:

This is how fully synchronized node looks at the moment:

You should also see a lot of resources being used on the server while initial synchronization is happening. Depending on your hardware, especially CPU and disk, initial synchronization might take even up to 24 hours.
After the node finishes bootstrapping, it’s not using as much resources.

Additional step: Depending on your firewall configuration you might need to add following exceptions to the iptables: