Requests from a sending wallet to a message delivery server.

Example message pre-creation request

When a sending wallet wants to create a message for delivery, the coinspark_message_pre_create request must be called first. This allows a wallet to verify whether the message delivery server will be willing to handle a particular request, without having to send all of the content immediately. It also enables the server to respond with a nonce that the sending wallet uses as the basis for a signature proving that they own the sender bitcoin address.

{
  "id": "any_request_id",
  "method": "coinspark_message_pre_create",
  "params": {
    "testnet": false,
    "sender": "1HDxhfeoSQmVNzTnZRLe2Z6nJ1LLAuGWpa",
    "ispublic": false,
    "recipients": [
      "14719bzrTyMvEPcr7ouv9R8utncL9fKJyf",
      "19ngVyAav9JLE6gVfeQB6zgHEpTZhxJ2qJ"
    ],
    "keepseconds": 604800,
    "salt": "ZmhqZHNma2poZ3NkZmdramRzZmdramhkc2ZranNjdmtqbmRma25k",
    "message": [
      {
        "mimetype": "text/plain",
        "filename": null,
        "bytes": 38
      },
      {
        "mimetype": "application/pdf",
        "filename": "Invoice AB123.pdf",
        "bytes": 384294
      }
    ]
  }
}

The sender address must belong to the sending wallet, i.e. it must have the corresponding private key, and it must also contain a non-zero balance of bitcoin (in the bitcoin testnet if testnet is true). The sending wallet will have to prove its ownership of the address in the subsequent coinspark_message_create call by signing a message using the corresponding private key.

The recipients element contains a list of one of more bitcoin addresses whose owners should be permitted to retrieve the message content. (The owners will have to prove they own this address by signing the retrieval request with the corresponding private key.) If ispublic is true then the message can be retrieved by anybody monitoring the blockchain. In this case the recipients element is meaningless and can be omitted.

The keepseconds elements specifies how long the sending wallet would like the message to be stored by the delivery server. The delivery server should verify if it is willing to store for the duration requested, and if not, return an error (see below). We recommend 604800 seconds (one week) as a reasonable guideline for all delivery servers to accept. Delivery servers are permitted to keep messages longer than the requested duration. The salt element is a binary string, base64 encoded, of the salt which will be used by the sending wallet for calculating the message hash.

The message contains a summary of the content of the message to be subsequently uploaded. For each item in the message, the MIME type, (optional) file name and size in bytes is specified. This enables the delivery server to determine whether it has the capacity to accept the desired message.

Example message pre-creation successful response

If the message delivery server is willing to accept the message outlined in the coinspark_message_pre_create request, it responds as follows:

{
  "id": "any_request_id",
  "result": {
    "sender": "1HDxhfeoSQmVNzTnZRLe2Z6nJ1LLAuGWpa",
    "nonce": "create 489752094984598745"
   }
}

The sender field contains the sender address that was supplied in this request, and which must be used to sign the nonce in the subsequent coinspark_message_create request. To avoid questions of encoding, the nonce may only use the ASCII characters 0x200x7E.

Example message pre-creation failure response

If the message delivery server is not willing to accept the message outlined in the coinspark_message_pre_create request, it responds as follows:

{
  "id": "any_request_id",
  "error": {
    "code": -11000,
    "message": "Sender not accepted"
  }
}

The following global error codes may be present:

code message meaning
-32700 Parse error Could not parse the JSON input received
-32600 Invalid request The JSON received is not a valid JSON-RPC request
-32601 Method not found The method in the request is not available
-32602 Invalid params The method params in the request are not valid
-32603 Internal error Something went wrong internally
-11000 Sender not accepted The sender bitcoin address or IP address will never be accepted, e.g. if this server only allows messages from certain senders.
-11001 Sender is suspended The sender bitcoin address or request IP address has been temporarily suspended, e.g. if they have already sent too many messages via this server.
-11002 Network not allowed The chosen network, as defined by the testnet parameter, is not accepted by this server.
-11010 No public messages The ispublic parameter is not allowed to be true, because this server doesn’t allow public messages.
-11011 Only public messages The ispublic parameter is not allowed to be false, because this server only allows public messages.
-11020 Too many recipients The recipients parameter contains too many elements.
-11021 Recipient not accepted The recipients parameter contains an address which is not accepted, e.g. because this server will only deliver messages to certain recipients.
-11022 Recipient is suspended The recipients parameter contains an address which has been temporarily suspended, e.g. because too many messages have been delivered to this recipient.
-11030 Duration not acceptable The keepseconds parameter is not acceptable, because this server is only willing to store messages for a shorter period of time.
-11040 Salt not acceptable The salt parameter is not acceptable, e.g. because it is the empty string or is too short to provide sufficient security.
-11050 Too many message parts The message contains too many individual message parts.
-11051 Total message too large The total number of bytes represented by the message elements is too large for this server to deliver.
-11052 MIME type not acceptable One of the message elements contains a mimetype which this server is not willing to deliver, e.g. because it is for text messages only.
-11053 File name not acceptable One of the message elements contains a filename which this server is not willing to deliver, e.g. because it is an .exe file.
-11054 Content too large One of the message elements is larger than this server is willing to deliver.

Example message creation request

If the coinspark_message_pre_create request was successful, the sending wallet can now call the coinspark_message_create method to actually create the message for delivery. The payload of this request is identical to coinspark_message_pre_create except:

  • There are nonce, pubkey and signature fields, to authenticate the sending wallet as the owner of the sender address.
  • There is a txid field, which contains the bitcoin transaction ID to which the message is being attached.
  • There are content fields containing the content itself, rather than bytes fields giving the proposed size of the content.
{
  "id": "any_request_id",
  "method": "coinspark_message_create",
  "params": {
    "testnet": false,
    "sender": "1HDxhfeoSQmVNzTnZRLe2Z6nJ1LLAuGWpa",
    "nonce": "create 489752094984598745",
    "pubkey": "03ad21a2ced244adb67fa4dd279a89405e3d5d98e85b2bafba94b030217b489d2b",
    "signature": "H8vEqnM253WI3BRqOz7nG+AkhnsYGAnne5YfLOG9Z4yzvLgnHiyF+WqI09p/wF948Pw0Ug6BeqmncT/oQI0VmoM=",
    "txid": "7908b807decb3a4ce70bb07f0091a80bc1789777d7e512e677bac9d4e4f111f1",
    "ispublic": false,
    "recipients": [
      "14719bzrTyMvEPcr7ouv9R8utncL9fKJyf",
      "19ngVyAav9JLE6gVfeQB6zgHEpTZhxJ2qJ"
    ],
    "keepseconds": 604800,
    "salt": "ZmhqZHNma2poZ3NkZmdramRzZmdramhkc2ZranNjdmtqbmRma25k",
    "message": [
      {
        "mimetype": "text/plain",
        "filename": null,
        "content": "UGF5bWVudCBmb3IgdGhlIGF0dGFjaGVkIGludm9pY2UgLSBCb2I="
      },
      {
        "mimetype": "application/pdf",
        "filename": "Invoice AB123.pdf",
        "content": "JVBERg== ..."
      }
    ]
  }
}

Both the sender and nonce must match those received in the response to coinspark_message_pre_create. The pubkey must contain the hexadecimal public key of the sender bitcoin address, and the signature must contain a base64-encoded bitcoin signature of the nonce by the private key corresponding to pubkey and sender.

Two types of signature content are supported: either (a) the output from Bitcoin Core’s signmessage command called with sender and nonce, or (b) a regular bitcoin transaction input signature of nonce using the private key for sender, as used in the scriptSig of transaction inputs.

The salt and content elements contain raw binary, base64 encoded. If mimetype is text/plain then the corresponding content should contain the text in UTF-8 encoding, base64 encoded, rather than a plain JSON string.

Example message creation success response

If the coinspark_message_create request was successful, the message delivery server sends back the following simple response, echoing the txid and keepseconds parameters passed with the request:

{
  "id": "any_request_id",
  "result": {
    "txid": "7908b807decb3a4ce70bb07f0091a80bc1789777d7e512e677bac9d4e4f111f1",
    "keepseconds": 604800,
  }
}

Example message creation failure response

If the coinspark_message_create request failed, the message delivery server responds as follows:

{
  "id": "any_request_id",
  "error": {
    "code": -11000,
    "message": "Sender not accepted"
  }
}

The possible list of error codes includes everything that might appear in a pre-creation failure response, plus the following additional possibilities:

code message meaning
-11055 Content mismatch One of the message elements contains a content field which is not valid according to the corresponding mimetype. (There is no obligation for message delivery servers to check this, but they can if they wish.)
-11080 Transaction ID invalid The txid field is not a valid bitcoin transaction ID.
-13000 Nonce not found The nonce provided does not match a nonce that was previously supplied by the message delivery server in the response to a coinspark_message_pre_create request.
-13010 Signature incorrect The signature field does not contain a base64-encoded bitcoin signature of the nonce by the owner of the sender address.
-13011 Pubkey incorrect The pubkey field does not contain a valid bitcoin public key in hexadecimal.
-13012 Pubkey address mismatch The pubkey field does not match the sender address.