CoinSpark allows text messages and files to be attached to any transaction.

CoinSpark messages allow bitcoin transactions to be enriched with additional content, such as an explanatory note, contracts, invoices, or even multimedia content such as images or videos. The message is transmitted from the sender to recipient(s) via a message delivery server, while the message’s presence is denoted by some message metadata added to the bitcoin transaction in an OP_RETURN output. This metadata contains the address of the delivery server, a list of output indexes for which the message is intended, and a hash of the full message content.

Try the CoinSpark Message script to send and receive CoinSpark messages using the regular Bitcoin Core client.

A CoinSpark message is defined as one of more pieces of content, each of which has the following information:

  • The MIME type of the piece of content. For text this would be text/plain.
  • Optional: the file name of the piece of content, in UTF-8 encoding.
  • The content itself. Text and HTML content should use UTF-8 encoding.

As well as regular bitcoin transactions, it is possible to attach CoinSpark messages to transactions which transfer CoinSpark assets from one party to another. The asset transfer metadata and message metadata can be combined together in a single OP_RETURN, since both use a highly efficient encoding scheme, and the message hash can be of variable length (subject to a lower limit).

The message hash is calculated from the message payload (as well as some random salt) and serves two related purposes. First, it enables the message recipient to be certain that the message was not modified in transit, since the hash is embedded in the bitcoin transaction by the sender and can be used to verify the payload by the recipient. Second, it automatically notarizes the message content on the bitcoin blockchain, so that both sender and recipient have a publicly verifiable proof of the message that was attached. This may be useful if the transaction has commercial value, and the information attached to the transaction contains an invoice, contract, or even delivery of some digital content. In order to make the hash usable in this way, it is recommend that the wallets of both the sender and recipient of a CoinSpark message store a permanent copy of each message and its salt.

The delivery process begins with a sending wallet contacting its preferred message delivery server with a message creation request. This request includes the bitcoin transaction ID, message hash salt, content payload, a list of bitcoin public keys belonging to permitted recipients, and the duration during which the message should be stored. Assuming the message delivery server is satisfied with the request, it creates a new entry in its local database containing all of the provided information.

Generally CoinSpark messages are intended for the recipients of one or more outputs of a bitcoin or asset transaction. The indices of these outputs are denoted within the message metadata, so that each recipient of a transaction knows whether they should attempt to retrieve an associated message or not. In order to obtain the message they must contact the delivery server specified within the metadata, specify the transaction ID, provide their bitcoin address, and sign a message retrieval request using the corresponding bitcoin private key. The delivery server checks the public key against the list it was provided, and that the signature on the request matches that public key. If so, it sends back all the message information in the response.

CoinSpark also allows public messages to be created, which can be used for broadcasting content to interested parties, while simultaneously authenticating and notarizing the broadcast content using the message hash on the bitcoin blockchain. The sending wallet denotes that a message is public when uploading it to the delivery server and embedding the appropriate flag in the message metadata. Any person or process monitoring the bitcoin blockchain can then retrieve the message from the delivery server without providing their bitcoin address or signing the retrieval request. Considering the potential number of requests, it is up to each delivery server to decide whether it will accept public messages and if it will limit the number of times they can be retrieved.

To get you started, we provide a free message delivery server at msg1|2| However it should be noted that the message delivery server is able to see the content of your messages, even if it protects that content from third parties. (It is not possible to encrypt message content for the recipient using their bitcoin public key because a regular bitcoin address is only a hash of that key.) If your messages contain sensitive information, or you are running a wallet service on behalf of other users, you may wish to run our open source delivery server on your own systems, or even implement your own.