Operate v0.1.0-beta.15 Operate View Source

Load and run Operate programs (known as "tapes") encoded in Bitcoin SV transactions.

Operate is a toolset to help developers build applications, games and services on top of Bitcoin (SV). It lets you write functions, called "Ops", and enables transactions to become small but powerful programs, capable of delivering new classes of services layered over Bitcoin.

Installation

The package is bundled with libsecp256k1 NIF bindings. libtool, automake and autogen are required in order for the package to compile.

The package can be installed by adding operate to your list of dependencies in mix.exs.

The most recent luerl package published on hex.pm is based on Lua 5.2 which may not be compatible with all Ops. It is recommended to override the luerl dependency with the latest development version to benefit from Lua 5.3.

def deps do
  [
    {:operate, "~> 0.1.0-beta.15"},
    {:luerl, github: "rvirding/luerl", branch: "develop", override: true}
  ]
end

Quick start

The agent can be used straight away without starting any processes. This will run without caching so should only be used for testing and kicking the tyres.

{:ok, tape} = Operate.load_tape(txid)
{:ok, tape} = Operate.run_tape(tape)

tape.result

See load_tape/2 and run_tape/2.

Process supervision

To enable caching the agent should be started as part of your applications process supervision tree.

children = [
  {Operate, [
    cache: Operate.Cache.ConCache,
  ]},
  {ConCache, [
    name: :operate,
    ttl_check_interval: :timer.minutes(1),
    global_ttl: :timer.minutes(10),
    touch_on_read: true
  ]}
]

Supervisor.start_link(children, strategy: :one_for_one)

Configuration

Operate can be configured with the following options. Additionally, any of these options can be passed to load_tape/2 and run_tape/2 to override the configuration.

:tape_adapter - The adapter module used to fetch the tape transaction.
:op_adaapter - The adapter module used to fetch the tape's Ops.
:cache - The cache module used for caching tapes and Ops.
:extensions - A list of extension modules to extend the VM state.
:aliases - A map of references to alias functions to alternative references.
:strict - Set false to disable strict mode and ignore missing and/or erring functions.

The default configuration:

tape_adapter: Operate.Adapter.Bob,
op_adapter: Operate.Adapter.OpApi,
cache: Operate.Cache.NoCache,
extensions: [],
aliases: %{},
strict: true

Link to this section Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

get_state(options \\ [])

Gets Operate's current VM state and config.

load_tape(txid, options \\ [])

Loads a tape from the given txid.

load_tape!(txid, options \\ [])

As load_tape/2, but returns the tape or raises an exception.

load_tapes_by(query, options \\ [])

Loads a tape from the given query.

load_tapes_by!(query, options \\ [])

As load_tapes_by/2, but returns the tapes or raises an exception.

prep_tape(tx, index \\ nil, options \\ [])

Prepare the tape from the given transaction. Optionally specify the output index of the tape.

prep_tape!(tx, index \\ nil, options \\ [])

As prep_tape/3, but returns the tape or raises an exception.

prep_tapes(txns, config \\ [], tapes \\ [])

Prepare the tapes from the given list of transactions.

run_tape(tape, options \\ [])

Runs the given tape executing each of the tape's cells and returns the modified and complete Operate.Tape.t/0 in an :ok / :error tuple pair.

run_tape!(tape, options \\ [])

As run_tape/2, but returns the tape or raises an exception.

start_link(options \\ [])

Starts an Operate agent process with the given options merged with the default config.

version()

Returns the current version number.

Link to this section Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_state(options \\ [])

Specs

get_state(keyword()) :: {Operate.VM.t(), map()}

Gets Operate's current VM state and config.

If a process has already been started then the existing VM and config is returned. Alternatively a new VM state is initiated and the default config returned. In either case any configuration option can be overridden.

Returns a tuple pair containing the VM state and a configuration map.

load_tape(txid, options \\ [])

Specs

load_tape(String.t(), keyword()) ::
  {:ok, Operate.Tape.t()} | {:error, String.t()}

Loads a tape from the given txid.

Fetchs the tape transaction output as well as all of the required functions, and returns a Operate.Tape.t/0 ready for execution in an :ok / :error tuple pair.

If an Operate agent process has already been started the existing config will be used. Otherwise a default config will be used. Any configuration option can be overridden.

Options

Refer to the list of accepted configuration options.

load_tape!(txid, options \\ [])

Specs

load_tape!(String.t(), keyword()) :: Operate.Tape.t()

As load_tape/2, but returns the tape or raises an exception.

load_tapes_by(query, options \\ [])

Specs

load_tapes_by(map(), keyword()) ::
  {:ok, [Operate.Tape.t(), ...]} | {:error, String.t()}

Loads a tape from the given query.

The expected format of the query will depend on the Operate.Adapter in use. The transactions as well as all required functions are loaded an a list of Operate.Tape.t/0 are returned in an :ok / :error tuple pair.

If an Operate agent process has already been started the existing config will be used. Otherwise a default config will be used. Any configuration option can be overridden.

Options

Refer to the list of accepted configuration options.

Examples

For example, if using the default Operate.Adapter.Bob adapter, a Bitquery can be provided. The project attribute cannot be used and unless otherwise specified, limit defaults to 10.

Operate.load_tapes_by(%{
  "find" => %{
    "out.tape.cell" => %{
      "$elemMatch" => %{
        "i" => 0,
        "s" => "1PuQa7K62MiKCtssSLKy1kh56WWU7MtUR5"
      }
    }
  }
})

load_tapes_by!(query, options \\ [])

Specs

load_tapes_by!(map(), keyword()) :: [Operate.Tape.t(), ...]

As load_tapes_by/2, but returns the tapes or raises an exception.

prep_tape(tx, index \\ nil, options \\ [])

Specs

prep_tape(Operate.BPU.Transaction.t(), integer() | nil, map() | keyword()) ::
  {:ok, Operate.Tape.t()} | {:error, String.t()}

Prepare the tape from the given transaction. Optionally specify the output index of the tape.

prep_tape!(tx, index \\ nil, options \\ [])

Specs

prep_tape!(Operate.BPU.Transaction.t(), integer() | nil, keyword()) ::
  Operate.Tape.t()

As prep_tape/3, but returns the tape or raises an exception.

prep_tapes(txns, config \\ [], tapes \\ [])

Specs

prep_tapes([Operate.BPU.Transaction.t(), ...], map() | keyword(), list()) ::
  {:ok, [Operate.Tape.t(), ...]} | {:error, String.t()}

Prepare the tapes from the given list of transactions.

run_tape(tape, options \\ [])

Specs

run_tape(Operate.Tape.t(), keyword()) ::
  {:ok, Operate.Tape.t()} | {:error, Operate.Tape.t()}

Runs the given tape executing each of the tape's cells and returns the modified and complete Operate.Tape.t/0 in an :ok / :error tuple pair.

If an Operate agent process has already been started the existing VM state and config will be used. Otherwise a new state and default config will be used. Any configuration option can be overridden.

Options

The accepted options are:

:extensions - A list of extension modules to extend the VM state.
:strict - Strict mode (defaults true). Disable to force the tape to ignore missing and/or erroring cells.
:state - Speficy a state which the tape begins execution with (defaults to nil).
:vm - Pass an already initiated VM state in which to run the tape.

run_tape!(tape, options \\ [])

Specs

run_tape!(Operate.Tape.t(), keyword()) :: Operate.Tape.t()

As run_tape/2, but returns the tape or raises an exception.

start_link(options \\ [])

Specs

start_link(keyword()) :: {:ok, pid()}

Starts an Operate agent process with the given options merged with the default config.

Options

Refer to the list of accepted configuration options.

version()

Specs

version() :: String.t()

Returns the current version number.