BLC Protocol

This page attempts to thoroughly and concisely document the BLC protocol, both to and from the server.
The protocol documented here is valid as of commit 4dc77c7 (protocol version: 1.2.0-stable)

---

General rules

These rules apply to just about everything, unless otherwise noted.

• All requests must be JSON encoded (through the use of your languages JSON library, or manually encoded by hand)
  • An invalid JSON request (one the server is unable to decode) will be replied to with a reply where success == False, and the request in the payload field.

General rules: client -> server

These rules apply to everything sent to the server from a client.

• All requests must contain a cmd field in the topmost level of the request, signifying the command the client wishes to execute.

Example request:

{
    "cmd": "check",
    "winning_string": "FOO123",
    "winning_hash": "d2deb74455fc29e7[...]",
    "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50"
}

General rules: server -> client

These rules apply to everything sent from the server to the client.

• All requests will contain the three fields: success, message and payload.
  • success - boolean (True/False) - shows whether or not the command was executed correctly.
  • message - string - used in the event a command failed execution for whatever reason.
    • This will be null if success == True
  • payload - JSON dict ({"foo": "bar"}) - contains the resulting payload a command gives back.
    • This will not be null if success == True
  • payload and message are mutually exclusive - if you have one, you can't have the other. One will be null.
  • The one exception to this mutual exclusivity is if the server is unable to JSON decode the request, it will send a reply with success == False, and the request in the payload.

Example success reply:

{
    "success": true,
    "message": null,
    "payload": {
        "hash": "d2deb74455fc29e7[...]"
    }
}

Example failure reply:

{
    "success": false,
    "message": "Something went wrong",
    "payload": null
}

---

• The commands here are documented in alphabetical order.
• Bean counter used here refers to the "coin count" attached to a given address.
• The address used in examples (da8d35596022cd2fb0f89efe3ff903fa88333b50) is a newly generated, non-used address.
• For brevity, many large hashes will be shortened, and indicated so by being appended with [...] (e.g. d2deb74455fc29e7[...])

check

This command allows clients (more specifically miners) to validate their work, and if it's accepted add it to the bean counter for the address given.

Example request:

{
    "cmd": "check",
    "winning_string": "FOO123",
    "winning_hash": "d2deb74455fc29e7[...]",
    "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50"
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "hash": "d2deb74455fc29e7[...]"
    }
}

check_addr

Allows clients to get information as to the bean counter of a given address.

Example request:

{
    "cmd": "check_addr",
    "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50"
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
        "amount": 7
    }
}

get_coin

Allows a client (more specifically a miner) to request the current difficulty of the server. The somewhat strange name is due to the fact that initially this would generate a random base string for miners to work from, as well as the difficulty.

Example request:

{
    "cmd": "get_coin"
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "difficulty": 7
    }
}

my_coins

Allows a user to get the amount of coins attached to their account. Somewhat deprecated because of the check_addr command, and is mostly used now by online wallets to verify the account details given by a user.

Example request:

{
    "cmd": "my_coins",
    "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
    "pwd": "95059[...]"
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "amount": 7
    }
}

register

Allows clients to register an address with the BlooCoin server.

• The address given must be 40 characters in length, no more, no less.
• Any characters are acceptable (not just alphanumeric), so you can go wild with vanity addresses if you so choose.
• The address mustn't exist already.

Example request:

{
    "cmd": "register",
    "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
    "pwd": "95059[...]"
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50"
    }
}

send_coin

This is the core of the BlooCoin ecosystem. This allows users to send coins from address to address.

• The amount field must be an integer, not a string representation of an integer.

Example request:

{
    "cmd": "send_coin",
    "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
    "pwd": "95059[...]",
    "to": "ff903fa88333[...]",
    "amount": 7
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "to": "ff903fa88333[...]",
        "from": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
        "amount": 7
    }
}

total_coins

Allows a client to query the total amount of coins in existence. Mostly used in network graphs on sites such as BlooHub.

Example request:

{
    "cmd": "total_coins"
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "amount": 1234
    }
}

transactions

Allows a client to pull a list of transactions (to and from) involving a given address. This requires the stored password, so you can't view any addresses transaction list.

Example request:

{
    "cmd": "transactions",
    "addr": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
    "pwd": "95059[...]"
}

Example reply:

{
    "success": true,
    "message": null,
    "payload": {
        "transactions": [
            {
                "from": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
                "to": "ff903fa88333[...]",
                "amount": 7
            },
            {
                "from": "ff903fa88333[...]",
                "to": "da8d35596022cd2fb0f89efe3ff903fa88333b50",
                "amount": 3
            }
        ]
    }
}