Manic v0.0.1 Manic.JSONEnvelope 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

Link to this type

payload()

View Source
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
}
Link to this type

t()

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

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

Link to this function

build(body)

View Source
build(map()) :: t()

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

Link to this function

parse_payload(env)

View Source
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.

Link to this function

verify(env)

View Source
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.

Returns the JSON Envelope in an :ok tuple, or returns an :error tuple with an exception or error message.

If the envelop contains no signature and public key, then no attempt at verification is made and the envelope is returned ok.