Manic.JSONEnvelope (Manic v0.1.1) View Source

Module implementing the Merchant API JSON Envelope Specification.

Every response payload from the Merchant API is encapsualted in a parent JSON object, which is signed by the miner's Miner ID.

Most manic functions return just the parsed payload, but behind the scenes the signature is automatically verified against the payload and an error is returned if verification fails.

Link to this section Summary

Types

Merchant API response payload.

t()

JSON Envelope.

Functions

Builds a JSON Envelope from the given [map][map/0].

Parses the given JSON Envelope's payload according it its specified mime type.

Verifies the given JSON Envelope, by cryptographically verifying the envelopes signature against the payload, using the public key in the envelope.

Link to this section Types

Specs

payload() :: %{required(String.t()) => String.t() | integer() | nil}

Merchant API response payload.

Depending on the request, the payload returned by the Marchant API can contain different fields. Manic automatically re-cases all keys in the map to snake-cased strings for a more idiomatic Elixir style.

Examples

The payload for a fee quote request:

%{
  "api_version" => String.t,
  "current_highest_block_hash" => String.t,
  "current_highest_block_height" => integer,
  "expiry_time" => String.t,
  "fees" => [
    %{
      "fee_type" => String.t,
      "mining_fee" => %{
        "bytes" => integer,
        "satoshis" => integer
      },
      "relay_fee" => %{
        "bytes" => integer,
        "satoshis" => integer
      }
    },
    ...
  ],
  "miner_id" => String.t,
  "miner_reputation" => String.t | nil,
  "timestamp" => String.t
}

Example payload from submiting new transactions:

%{
  "api_version" => String.t,
  "current_highest_block_hash" => String.t,
  "current_highest_block_height" => integer,
  "miner_id" => String.t,
  "return_result" => String.t,
  "result_description" => String.t,
  "timestamp" => String.t,
  "txid" => String.t,
  "tx_scond_mempool_expiry" => integer
}

Example payload from querying a transaction's status:

%{
  "api_version" => String.t,
  "block_hash" => String.t,
  "block_height" => integer,
  "confirmations" => integer,
  "miner_id" => String.t,
  "return_result" => String.t,
  "result_description" => String.t,
  "timestamp" => String.t,
  "tx_scond_mempool_expiry" => integer
}

Specs

t() :: %Manic.JSONEnvelope{
  encoding: String.t(),
  mimetype: String.t(),
  payload: String.t(),
  public_key: String.t(),
  signature: String.t(),
  verified: boolean()
}

JSON Envelope.

Each parent JSON object contains a JSON encoded payload, signature and public key. The public key can be used to verify the signature against the payload.

Link to this section Functions

Specs

build(map()) :: t()

Builds a JSON Envelope from the given [map][map/0].

Specs

parse_payload(t()) :: {:ok, map()} | {:error, Exception.t()}

Parses the given JSON Envelope's payload according it its specified mime type.

Returns the result in an :ok / :error tuple pair.

The payload's keys are automatically re-cased to snake-cased strings for a more idiomatic Elixir style.

Specs

verify(t() | map()) :: {:ok, t()} | {:error, Exception.t() | String.t()}

Verifies the given JSON Envelope, by cryptographically verifying the envelopes signature against the payload, using the public key in the envelope.

Adds the boolean result to the :verified key, and returns the JSON Envelope in an :ok tuple.