Behaviour for atomic Tempo state stores used by MPP.Methods.Tempo.

Prevents replay attacks by tracking which transaction hashes have already been used. HMAC-bound challenges prevent cross-request replay; this store prevents a client from resubmitting the same signed transaction within the store's TTL window.

Important: The store's TTL must be ≥ your challenge expires_in to ensure a tx hash cannot be evicted and replayed while the challenge is still valid. A good default is 2× the challenge expiry.

Built-in Store

MPP.Tempo.ConCacheStore provides an ETS-based implementation with automatic TTL expiry via ConCache. It is started by the :mpp application as the default store, so replay protection is on out of the box (issue #7). For most single-node deployments this is all you need; for multi-node, configure a shared backend (Redis/Postgres) as your :store.

Custom Implementations

Implement this behaviour with your choice of backend (Redis, database, etc.) for custom needs. Store lifecycle and cleanup are the consumer's responsibility.

Fee sponsorship additionally requires update/3. The update callback must be atomic for one key and must honor :ttl_ms without expiring the value earlier. All nodes and endpoints sponsoring the same wallet must select the same physical backend. Separate store instances provide separate bounds even when their module and configuration are otherwise identical.

The transaction path may delete/2 a reserved slot after a definite pre-broadcast failure (hosted fill, co-sign, missing config, simulate revert) so the same signed bytes remain retriable. The reservation value is an attempt token; delete/2 is compare-and-delete on that token so a delayed release cannot remove a later attempt's reservation or mark after TTL eviction. delete/2 is optional: stores that omit it fall back to update/3 that compares the stored value to the expected token, otherwise the key is retained until TTL expiry (the conservative retain path).

Deployment Strategies

The store choice depends on your deployment topology:

• Single node: ConCacheStore is sufficient — all requests hit the same ETS table.
• Multi-node with sticky routing: If your load balancer pins clients to specific nodes (e.g., Fly.io's fly-replay with cookie-based sticky sessions, or consistent hashing by session ID), per-node ConCacheStore is effectively global — the same client always hits the same node's store.
• Multi-node without sticky routing: Use a shared backend (Redis, Postgres) to ensure a tx replayed on a different node is still caught.

Keys are formatted as "mpp:charge:<lowercase_hex_value>" where the value is the transaction hash (for type="hash") or the full serialized transaction hex (for type="transaction").

Multi-tenant key prefixes

When several endpoints share one ConCacheStore instance, pass a distinct :key_prefix in the store opts so identical transaction hashes do not collide:

"store" => {MPP.Tempo.ConCacheStore, name: :shared_dedup, key_prefix: "billing:"}

Prefixes are prepended to every backing key (mppx Store.from/2 parity). Default is no prefix — behavior is unchanged when omitted.

Example

defmodule MyApp.PaymentStore do
  @behaviour MPP.Tempo.Store

  def get(key) do
    case :ets.lookup(:payment_dedup, key) do
      [{^key, value}] -> {:ok, value}
      [] -> :not_found
    end
  end

  def put(key, value) do
    :ets.insert(:payment_dedup, {key, value})
    :ok
  end

  def check_and_mark(key, value) do
    if :ets.insert_new(:payment_dedup, {key, value}) do
      :ok
    else
      {:error, :already_exists}
    end
  end

  # Compare and delete in one ETS operation; a lookup followed by a
  # delete would let a concurrent reserve slip in between.
  def delete(key, expected) do
    :ets.select_delete(:payment_dedup, [{{key, expected}, [], [true]}])
    :ok
  end
end

Then pass it in method_config:

plug MPP.Plug,
  method: MPP.Methods.Tempo,
  method_config: %{
    "rpc_url" => "https://rpc.moderato.tempo.xyz",
    "store" => MyApp.PaymentStore
  }