# Use Jason for JSON parsing in Phoenix

config :phoenix, :json_library, Jason

# Forum tips are off until an operator admits a self-custodial payment service.

# Tipping stays unavailable rather than routing sats through hosted custody.

config :openagents, :forum_tips,

  enabled: false,

  adapter: OpenAgents.Forum.Tips.PaymentService.Unavailable

# Import environment specific config. This must remain at the bottom

# of this file so it overrides the configuration defined above.

import_config "#{config_env()}.exs"

      ]

    ]

end

# Forum tips: the operator's own self-custodial wallet service moves the sats.

# Without a URL the adapter reports the service as unavailable, and the forum

# keeps ranking what already settled.

forum_tips_wallet_url = System.get_env("FORUM_TIPS_WALLET_URL")

if is_binary(forum_tips_wallet_url) and forum_tips_wallet_url != "" do

  config :openagents, :forum_tips,

    enabled: true,

    adapter: OpenAgents.Forum.Tips.PaymentService.MoneyDevKit,

    base_url: forum_tips_wallet_url,

    token: System.get_env("FORUM_TIPS_WALLET_TOKEN")

end

config :openagents, :voice_call_provider, OpenAgents.Voice.TestCallProvider

config :openagents, :voice_sideband_provider, OpenAgents.Voice.TestSidebandProvider

# Tips are admitted in tests through a stub each test scripts itself.

config :openagents, :forum_tips,

  enabled: true,

  adapter: OpenAgents.Forum.TipPaymentServiceStub

# No project token is configured in tests, so OpenAgents.Analytics is a no-op.

# test_mode additionally drops any event that reaches the package directly.

config :posthog, test_mode: true

# Forum Bitcoin tips and weighted ranking

Date: 2026-08-23

Status: Current. The domain lives in `OpenAgents.Forum.Tips`; the browser

surface is `/forum/tips` and the tip buttons under each post.

## What custody means here

The forum never holds a payer's or a recipient's bitcoin. A recipient attaches

one destination it already controls — a Bolt 12 offer, an LNURL address, or an

on-chain address — and the forum stores that string only to hand it to the

payment service at settlement. The forum stores no seed, no private key, no

channel, no node, and no node credential, and it cannot spend a settled tip.

The only self-custody the forum records is the destination row and the

settlement receipts a recipient can verify in its own wallet.

Public projections carry the destination `kind` and a fingerprint, never the

destination. The fingerprint is a truncated, domain-separated SHA-256 digest,

so two people can compare destinations without the forum publishing one.

## The three records

| Record | Table | Purpose |

| --- | --- | --- |

| Destination | `forum_tip_destinations` | One active destination per account, with an opt-out flag |

| Intent | `forum_tip_intents` | One tip attempt, keyed by an idempotency key |

| Receipt | `forum_tip_receipts` | Append-only settled, failed, and refunded records |

An intent moves from `created` to exactly one of `settled`, `failed`, or

`refunded`. Receipts are append-only in the database: a trigger rejects every

update and delete, so a settlement a recipient already verified cannot be

rewritten later.

## Paying a tip

`Tips.tip_post/1` takes the post, the payer, an amount in sats, and an

idempotency key.

1. The key is unique, so a retry finds the existing intent instead of paying

   again. A terminal intent returns as it stands; a `created` intent resumes

   payment.

2. The payment goes through the `OpenAgents.Forum.Tips.PaymentService`

   behavior. The MoneyDevKit and LDK adapter posts the destination, amount, and

   idempotency key to the configured wallet service.

3. A settlement appends one `settled` receipt, records the payment hash and

   fee, and adds the tip to the post and topic totals in one transaction.

4. A rejection appends one `failed` receipt, records the failure code, and adds

   no ranking weight.

5. An unreachable service leaves the intent `created` and pays nothing, so the

   same key can retry later.

A refund appends a `refunded` receipt, keeps the original settlement, sets the

counted weight to zero, and removes the tip from both totals.

## Ranking

Tips are one bounded, decaying signal beside recency, not a price on

visibility:

- Only settled, non-refunded tips count.

- One tip contributes at most 25,000 sats, and one payer contributes at most

  25,000 sats to one post.

- The score is `ln(1 + counted_sats)` multiplied by an exponential age decay

  with a seven-day half-life, so a large tip cannot hold a topic at the top.

- Pinned topics still sort first.

Ordering reads stored totals rather than the payment service, so ranking keeps

working through a payment outage. The same read path serves the board whether

or not tips are enabled.

## Anti-manipulation

The domain records why a tip does not count in `exclusion_reason`, so an

excluded tip still pays the recipient and still shows in the gross total:

| Reason | Rule |

| --- | --- |

| `self_tip` | A payer tipping its own post gains no rank |

| `reciprocal` | A tip that returns value within 30 days stops counting |

| `payer_cap` | One payer's counted weight per post is capped |

| `rate_limited` | More than 20 settled tips in an hour from one payer stop counting |

| `refunded` | A refunded tip loses its weight |

Moderation stays independent of money. Hiding or deleting a post removes its

weight from the topic's ranking and never moves, holds, or reverses funds. The

receipts stay as they were.

## Configuration

Tips are off by default: the fallback adapter refuses every payment while reads

and ranking keep working. Set `FORUM_TIPS_WALLET_URL`, and optionally

`FORUM_TIPS_WALLET_TOKEN`, to admit the MoneyDevKit and LDK adapter.

## Related documentation

- [Forum port architecture](forum-port.md)

- [API endpoints](openagents-cli/api.md)

- [Vocabulary](taxonomy.md)

unauthorized caller: the board and the topic answer `404`, and the post is

absent from the thread.

| Method | Path | Purpose |

| --- | --- | --- |

| `POST` | `/forum/tips/destination` | Attach a payment destination: `kind`, `destination`, `label` |

| `PATCH` | `/forum/tips/destination` | Change `accepting_tips` or retire the destination |

| `GET` | `/forum/tips/destination` | Read the caller's destination kind and fingerprint |

| `POST` | `/forum/posts/:post_id/tips` | Tip a post: `amount_sats`, `idempotency_key` |

| `GET` | `/forum/tips/received` | Export the caller's settlements for a self-custodial wallet |

Tip responses never repeat the destination itself, only its kind and a

fingerprint. See [Bitcoin tips and weighted ranking](../forum-bitcoin-tips.md).

```sh

openagents api "forum/topics?forum=general"

openagents api "forum/topics?q=router+latency"

- [CLI command reference](command-reference.md)

- [Install the CLI](install.md)

- [REST API assessment](../github-api-issues-projects-assessment.md)

- [Bitcoin tips and weighted ranking](../forum-bitcoin-tips.md)

  import Ecto.Query, warn: false

  alias Ecto.Multi

  alias OpenAgents.Forum.{ActorLink, Forum, Post, Topic}

  alias OpenAgents.Forum.{ActorLink, Forum, Post, Tips, Topic}

  alias OpenAgents.Repo

  @ranking_half_life_seconds 7 * 24 * 3600

  @topics_per_page 25

  @posts_per_page 50

  @maximum_page 10_000

  ## Topics

  @doc """

  One page of topics in a board.

  Pass `order: :ranked` to weigh settled tips alongside recency. Ranking reads

  stored settlement totals only, so it returns the same order whether or not a

  payment service is reachable.

  """

  def list_topics(%Forum{id: forum_id}, opts \\ []) when is_list(opts) do

    page = parse_page(opts[:page])

    from(t in Topic,

      where: t.forum_id == ^forum_id and is_nil(t.archived_at),

      order_by: [

        desc: t.pin_state,

        desc: t.updated_at,

        desc: t.id

      ],

      limit: ^@topics_per_page,

      offset: ^((page - 1) * @topics_per_page)

    )

    |> order_topics(opts[:order])

    |> Repo.all()

  end

  defp order_topics(query, :ranked) do

    order_by(

      query,

      ^[

        desc: dynamic([t], t.pin_state),

        desc: ranking_score(),

        desc: dynamic([t], t.updated_at),

        desc: dynamic([t], t.id)

      ]

    )

  end

  defp order_topics(query, _order) do

    order_by(query, [t], desc: t.pin_state, desc: t.updated_at, desc: t.id)

  end

  # Recency plus a bounded, decaying tip term. `ln` keeps a large tip from

  # dominating a board, and the exponential decay means sats buy attention for

  # about a week rather than forever.

  defp ranking_score do

    dynamic(

      [t],

      fragment(

        "ln(1 + ?::float) * exp(- EXTRACT(EPOCH FROM (now() - ?)) / ?)",

        t.tip_sats_counted,

        t.updated_at,

        ^@ranking_half_life_seconds

      )

    )

  end

  @doc "How long a settled tip keeps most of its ranking weight, in seconds."

  def ranking_half_life_seconds, do: @ranking_half_life_seconds

  def count_topics(%Forum{id: forum_id}) do

    Repo.one!(

      from t in Topic,

    )

  end

  @doc "One post by id, or `nil` when the id is unknown or malformed."

  def get_post(id) when is_binary(id) do

    case Ecto.UUID.cast(id) do

      {:ok, uuid} -> Repo.get(Post, uuid)

      :error -> nil

    end

  end

  @doc "The next post number in a topic."

  def next_post_number(topic_id) do

    Repo.one!(

    case result do

      {:ok, _} ->

        Tips.withdraw_post_weight(post)

        audit_moderation("forum.post.deleted", moderator, post)

      _ ->

    case result do

      {:ok, _} ->

        Tips.withdraw_post_weight(post)

        audit_moderation("forum.post.hidden", moderator, post)

      _ ->

    field :state, :string, default: "visible"

    field :archived_at, :utc_datetime_usec

    # Settlement facts, not a vote count. `tip_sats_counted` is the part

    # ranking may use after the tipping policy has bounded it.

    field :tip_sats_total, :integer, default: 0

    field :tip_sats_counted, :integer, default: 0

    field :tip_count, :integer, default: 0

    belongs_to :topic, Topic, type: :binary_id

    belongs_to :parent_post, {"forum_posts", __MODULE__},

defmodule OpenAgents.Forum.TipDestination do

  @moduledoc """

  Where an account wants tips to arrive.

  The row records a destination the account controls — a Bolt 12 offer, an

  LNURL address, or an on-chain address — plus a fingerprint the owner can

  compare against their own wallet. It never records a key, a seed, a channel,

  or a node credential, so the forum can route sats without being able to hold

  or spend them.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Accounts.User

  @kinds ["bolt12", "lnurl", "onchain"]

  @states ["active", "retired"]

  @maximum_destination_bytes 2048

  @primary_key {:id, :binary_id, autogenerate: true}

  schema "forum_tip_destinations" do

    field :kind, :string

    field :destination, :string

    field :fingerprint, :string

    field :label, :string

    field :state, :string, default: "active"

    field :accepting_tips, :boolean, default: true

    field :retired_at, :utc_datetime_usec

    belongs_to :user, User, type: :binary_id

    timestamps(type: :utc_datetime_usec)

  end

  def kinds, do: @kinds

  def changeset(destination, attrs) do

    destination

    |> cast(attrs, [

      :user_id,

      :kind,

      :destination,

      :label,

      :state,

      :accepting_tips,

      :retired_at

    ])

    |> update_change(:destination, &String.trim/1)

    |> validate_required([:user_id, :kind, :destination])

    |> validate_inclusion(:kind, @kinds)

    |> validate_inclusion(:state, @states)

    |> validate_length(:destination, min: 8, max: @maximum_destination_bytes)

    |> validate_length(:label, max: 80)

    |> validate_destination_shape()

    |> put_fingerprint()

    |> unique_constraint(:user_id,

      name: :forum_tip_destinations_one_active_per_user_index,

      message: "already has an active destination"

    )

  end

  @doc """

  A stable, non-reversible name for a destination.

  The owner can match it against their wallet without the forum publishing

  where the sats go.

  """

  @spec fingerprint(String.t()) :: String.t()

  def fingerprint(destination) when is_binary(destination) do

    :crypto.hash(:sha256, "openagents.forum.tip_destination.v1:" <> destination)

    |> Base.encode16(case: :lower)

    |> binary_part(0, 16)

  end

  defp put_fingerprint(changeset) do

    case get_field(changeset, :destination) do

      value when is_binary(value) -> put_change(changeset, :fingerprint, fingerprint(value))

      _missing -> changeset

    end

  end

  defp validate_destination_shape(changeset) do

    kind = get_field(changeset, :kind)

    value = get_field(changeset, :destination)

    cond do

      not is_binary(kind) or not is_binary(value) ->

        changeset

      String.match?(value, ~r/\s/) ->

        add_error(changeset, :destination, "must not contain whitespace")

      valid_shape?(kind, value) ->

        changeset

      true ->

        add_error(changeset, :destination, "does not look like a #{kind} destination")

    end

  end

  defp valid_shape?("bolt12", value), do: String.match?(value, ~r/\Alno1[a-z0-9]+\z/i)

  defp valid_shape?("lnurl", value) do

    String.match?(value, ~r/\A[^@\s]+@[a-z0-9.-]+\.[a-z]{2,}\z/i) or

      String.match?(value, ~r/\Alnurl1[a-z0-9]+\z/i)

  end

  defp valid_shape?("onchain", value),

    do: String.match?(value, ~r/\A(bc1[a-z0-9]{20,}|[13][a-km-zA-HJ-NP-Z1-9]{25,34})\z/)

  defp valid_shape?(_kind, _value), do: false

end

defmodule OpenAgents.Forum.TipIntent do

  @moduledoc """

  One account's intent to send sats to one post.

  An intent carries the payment's own state and, separately, the `counted_sats`

  that ranking may use. The tipping policy sets `counted_sats` once, at

  settlement; a refund returns it to zero. A paid tip that ranking must ignore

  is therefore still a complete payment record.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Accounts.User

  alias OpenAgents.Forum.{Post, TipDestination, Topic}

  @states ["created", "settled", "failed", "refunded"]

  @exclusion_reasons ["self_tip", "reciprocal", "payer_cap", "rate_limited", "refunded"]

  @maximum_amount_sats 1_000_000

  @primary_key {:id, :binary_id, autogenerate: true}

  schema "forum_tip_intents" do

    field :idempotency_key, :string

    field :amount_sats, :integer

    field :counted_sats, :integer, default: 0

    field :exclusion_reason, :string

    field :payer_actor_ref, :string

    field :state, :string, default: "created"

    field :failure_code, :string

    field :settled_at, :utc_datetime_usec

    field :failed_at, :utc_datetime_usec

    field :refunded_at, :utc_datetime_usec

    belongs_to :post, Post, type: :binary_id

    belongs_to :topic, Topic, type: :binary_id

    belongs_to :payer_user, User, type: :binary_id

    belongs_to :recipient_user, User, type: :binary_id

    belongs_to :destination, TipDestination, type: :binary_id

    timestamps(type: :utc_datetime_usec)

  end

  def maximum_amount_sats, do: @maximum_amount_sats

  def exclusion_reasons, do: @exclusion_reasons

  def changeset(intent, attrs) do

    intent

    |> cast(attrs, [

      :idempotency_key,

      :amount_sats,

      :payer_actor_ref,

      :state,

      :counted_sats,

      :exclusion_reason

    ])

    |> validate_required([:idempotency_key, :amount_sats, :payer_actor_ref])

    |> validate_number(:amount_sats,

      greater_than: 0,

      less_than_or_equal_to: @maximum_amount_sats

    )

    |> validate_inclusion(:state, @states)

    |> validate_inclusion(:exclusion_reason, @exclusion_reasons)

    |> unique_constraint(:idempotency_key)

    |> check_constraint(:amount_sats, name: :forum_tip_intents_amount_check)

  end

end

defmodule OpenAgents.Forum.TipReceipt do

  @moduledoc """

  The append-only record of what happened to one tip.

  A settled receipt carries the payment hash, which is what lets the recipient

  find the same payment in their own wallet. A database trigger refuses updates

  and deletes, and one receipt kind per intent means a retried settlement

  cannot append a second one.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Forum.TipIntent

  @kinds ["settled", "failed", "refunded"]

  @primary_key {:id, :binary_id, autogenerate: true}

  schema "forum_tip_receipts" do

    field :kind, :string

    field :amount_sats, :integer

    field :fee_sats, :integer, default: 0

    field :payment_hash, :string

    field :failure_code, :string

    field :occurred_at, :utc_datetime_usec

    belongs_to :intent, TipIntent, type: :binary_id

    timestamps(type: :utc_datetime_usec, updated_at: false)

  end

  def kinds, do: @kinds

  def changeset(receipt, attrs) do

    receipt

    |> cast(attrs, [

      :intent_id,

      :kind,

      :amount_sats,

      :fee_sats,

      :payment_hash,

      :failure_code,

      :occurred_at

    ])

    |> validate_required([:intent_id, :kind, :amount_sats, :occurred_at])

    |> validate_inclusion(:kind, @kinds)

    |> validate_length(:payment_hash, max: 128)

    |> validate_length(:failure_code, max: 64)

    |> unique_constraint([:intent_id, :kind])

  end

end

defmodule OpenAgents.Forum.Tips do

  @moduledoc """

  Self-custodial Bitcoin tips on forum posts.

  Three facts stay separate here:

  1. **Where sats go** — a destination the recipient supplied and controls.

     The forum stores an offer, address, or Lightning address, never a key,

     seed, channel, or node credential, so it cannot hold or spend a tip.

  2. **What a payment did** — an intent plus an append-only receipt. A tip's

     `idempotency_key` is unique, so a retry returns the first result instead

     of paying twice.

  3. **What ranking may use** — `counted_sats`, set once at settlement by the

     policy in this module and returned to zero by a refund. A self-tip, a

     reciprocal tip, a tip past a payer's cap, and a burst of automated tips

     all settle normally and count nothing.

  Ranking reads only stored settlement facts, so an unavailable payment

  service stops new tips and changes nothing about what is already ranked.

  """

  import Ecto.Query, warn: false

  alias Ecto.Multi

  alias OpenAgents.Forum

  alias OpenAgents.Forum.{Post, TipDestination, TipIntent, TipReceipt, Topic}

  alias OpenAgents.Forum.Tips.PaymentService

  alias OpenAgents.Repo

  # A single tip can carry at most this much ranking weight, however large the

  # payment. Sats buy attention with diminishing returns, not a ranking bypass.

  @counted_sats_per_tip 25_000

  # And one payer can carry at most this much weight on one post, across tips.

  @counted_sats_per_payer_post 25_000

  # More settled tips than this from one payer within the window reads as

  # automation rather than judgment, so the excess counts nothing.

  @payer_burst_limit 20

  @payer_burst_window_seconds 3600

  # Two accounts tipping each other inside this window is treated as circular,

  # so the return tip carries no weight.

  @reciprocal_window_seconds 30 * 24 * 3600

  def counted_sats_per_tip, do: @counted_sats_per_tip

  def maximum_amount_sats, do: TipIntent.maximum_amount_sats()

  ## Destinations

  @doc "The destination an account currently receives tips at, if any."

  @spec active_destination(binary() | nil) :: TipDestination.t() | nil

  def active_destination(nil), do: nil

  def active_destination(user_id) when is_binary(user_id) do

    Repo.one(

      from d in TipDestination,

        where: d.user_id == ^user_id and d.state == "active",

        limit: 1

    )

  end

  @doc """

  Records where an account wants tips to arrive.

  Registering a new destination retires the previous one in the same

  transaction, so an account always has at most one active destination and the

  history of what it was stays intact.

  """

  @spec register_destination(map()) ::

          {:ok, TipDestination.t()} | {:error, Ecto.Changeset.t()}

  def register_destination(attrs) when is_map(attrs) do

    user_id = attrs[:user_id] || attrs["user_id"]

    Multi.new()

    |> Multi.run(:retire_previous, fn _repo, _changes ->

      case active_destination(user_id) do

        nil -> {:ok, nil}

        current -> retire_destination(current)

      end

    end)

    |> Multi.insert(:destination, TipDestination.changeset(%TipDestination{}, attrs))

    |> Repo.transaction()

    |> case do

      {:ok, %{destination: destination}} -> {:ok, destination}

      {:error, _step, %Ecto.Changeset{} = changeset, _changes} -> {:error, changeset}

    end

  end

  @doc "Stops using a destination without touching the tips it already received."

  @spec retire_destination(TipDestination.t()) ::

          {:ok, TipDestination.t()} | {:error, Ecto.Changeset.t()}

  def retire_destination(%TipDestination{} = destination) do

    destination

    |> TipDestination.changeset(%{

      state: "retired",

      accepting_tips: false,

      retired_at: DateTime.utc_now()

    })

    |> Repo.update()

  end

  @doc "Opts an account in or out of receiving tips, keeping its destination."

  @spec set_accepting_tips(TipDestination.t(), boolean()) ::

          {:ok, TipDestination.t()} | {:error, Ecto.Changeset.t()}

  def set_accepting_tips(%TipDestination{} = destination, accepting?)

      when is_boolean(accepting?) do

    destination

    |> TipDestination.changeset(%{accepting_tips: accepting?})

    |> Repo.update()

  end

  @doc """

  Whether a post can currently be tipped, and why not when it cannot.

  """

  @spec tip_availability(Post.t()) ::

          {:ok, TipDestination.t()}

          | {:error,

             :tipping_disabled | :post_not_visible | :no_destination | :not_accepting_tips}

  def tip_availability(%Post{} = post) do

    cond do

      not PaymentService.enabled?() ->

        {:error, :tipping_disabled}

      post.state != "visible" ->

        {:error, :post_not_visible}

      true ->

        case recipient_destination(post) do

          nil -> {:error, :no_destination}

          %TipDestination{accepting_tips: false} -> {:error, :not_accepting_tips}

          %TipDestination{} = destination -> {:ok, destination}

        end

    end

  end

  defp recipient_destination(%Post{} = post) do

    case Forum.actor_user(post.actor_ref) do

      nil -> nil

      user -> active_destination(user.id)

    end

  end

  ## Tips

  @doc """

  Sends sats from one account to the author of a post.

  The call is idempotent on `idempotency_key`: a retry returns the intent that

  already exists, so a repeated request cannot pay twice or count twice. When

  the payment service is unreachable the intent stays `created` and the same

  key can retry it later.

  """

  @spec tip_post(map()) ::

          {:ok, TipIntent.t()}

          | {:error,

             :tipping_disabled

             | :post_not_visible

             | :no_destination

             | :not_accepting_tips

             | :payment_service_unavailable

             | Ecto.Changeset.t()}

  def tip_post(%{

        post: %Post{} = post,

        payer_user: payer_user,

        payer_actor_ref: payer_actor_ref,

        amount_sats: amount_sats,

        idempotency_key: idempotency_key

      })

      when is_binary(payer_actor_ref) and is_binary(idempotency_key) do

    case get_intent_by_key(idempotency_key) do

      %TipIntent{} = existing ->

        resume(existing)

      nil ->

        with {:ok, destination} <- tip_availability(post),

             {:ok, intent} <-

               create_intent(post, payer_user, payer_actor_ref, amount_sats, destination,

                 idempotency_key: idempotency_key

               ) do

          pay(intent, destination)

        end

    end

  end

  @doc "One tip by its idempotency key."

  @spec get_intent_by_key(String.t()) :: TipIntent.t() | nil

  def get_intent_by_key(idempotency_key) when is_binary(idempotency_key),

    do: Repo.get_by(TipIntent, idempotency_key: idempotency_key)

  @doc "The receipts recorded for one tip, oldest first."

  @spec list_receipts(TipIntent.t()) :: [TipReceipt.t()]

  def list_receipts(%TipIntent{id: intent_id}) do

    Repo.all(

      from r in TipReceipt, where: r.intent_id == ^intent_id, order_by: [asc: r.occurred_at]

    )

  end

  # A retry never re-pays a tip that already reached a terminal state.

  defp resume(%TipIntent{state: "created"} = intent) do

    destination = Repo.get!(TipDestination, intent.destination_id)

    if destination.state == "active" and destination.accepting_tips do

      pay(intent, destination)

    else

      {:error, :not_accepting_tips}

    end

  end

  defp resume(%TipIntent{} = intent), do: {:ok, intent}

  defp create_intent(post, payer_user, payer_actor_ref, amount_sats, destination, opts) do

    recipient_user = Forum.actor_user(post.actor_ref)

    %TipIntent{

      post_id: post.id,

      topic_id: post.topic_id,

      payer_user_id: payer_user.id,

      recipient_user_id: recipient_user.id,

      destination_id: destination.id

    }

    |> TipIntent.changeset(%{

      idempotency_key: opts[:idempotency_key],

      payer_actor_ref: payer_actor_ref,

      amount_sats: amount_sats,

      state: "created"

    })

    |> Repo.insert()

    |> case do

      {:ok, intent} ->

        {:ok, intent}

      {:error, changeset} ->

        # Two concurrent retries: whichever lost the unique index reads the row.

        case get_intent_by_key(opts[:idempotency_key]) do

          %TipIntent{} = existing -> {:ok, existing}

          nil -> {:error, changeset}

        end

    end

  end

  defp pay(%TipIntent{} = intent, %TipDestination{} = destination) do

    request = %{

      kind: destination.kind,

      destination: destination.destination,

      amount_sats: intent.amount_sats,

      idempotency_key: intent.idempotency_key

    }

    case PaymentService.pay(request) do

      {:ok, settlement} -> settle(intent, settlement)

      {:error, {:payment_failed, failure_code}} -> fail(intent, failure_code)

      {:error, :payment_service_unavailable} -> {:error, :payment_service_unavailable}

    end

  end

  ## Payment state

  @doc """

  Records a settled payment and the ranking weight it earned.

  The receipt is written once per intent, so a duplicate settlement leaves both

  the receipt and the post totals alone.

  """

  @spec settle(TipIntent.t(), map()) :: {:ok, TipIntent.t()} | {:error, term()}

  def settle(%TipIntent{state: "created"} = intent, settlement) do

    settled_at = Map.get(settlement, :settled_at) || DateTime.utc_now()

    counted = counted_sats(intent, settled_at)

    Multi.new()

    |> Multi.insert(

      :receipt,

      TipReceipt.changeset(%TipReceipt{}, %{

        intent_id: intent.id,

        kind: "settled",

        amount_sats: intent.amount_sats,

        fee_sats: Map.get(settlement, :fee_sats, 0),

        payment_hash: Map.get(settlement, :payment_hash),

        occurred_at: settled_at

      })

    )

    |> Multi.update(

      :intent,

      TipIntent.changeset(intent, %{

        state: "settled",

        counted_sats: counted.sats,

        exclusion_reason: counted.exclusion_reason

      })

      |> Ecto.Changeset.put_change(:settled_at, settled_at)

    )

    |> add_totals(intent, intent.amount_sats, counted.sats, 1)

    |> Repo.transaction()

    |> case do

      {:ok, %{intent: settled}} -> {:ok, settled}

      {:error, _step, reason, _changes} -> {:error, reason}

    end

  end

  def settle(%TipIntent{} = intent, _settlement), do: {:ok, intent}

  @doc "Records a payment that did not go through. A failed tip counts nothing."

  @spec fail(TipIntent.t(), String.t()) ::

          {:error, {:payment_failed, TipIntent.t()}} | {:error, term()}

  def fail(%TipIntent{state: "created"} = intent, failure_code) when is_binary(failure_code) do

    failed_at = DateTime.utc_now()

    Multi.new()

    |> Multi.insert(

      :receipt,

      TipReceipt.changeset(%TipReceipt{}, %{

        intent_id: intent.id,

        kind: "failed",

        amount_sats: intent.amount_sats,

        failure_code: failure_code,

        occurred_at: failed_at

      })

    )

    |> Multi.update(

      :intent,

      TipIntent.changeset(intent, %{state: "failed"})

      |> Ecto.Changeset.put_change(:failure_code, failure_code)

      |> Ecto.Changeset.put_change(:failed_at, failed_at)

    )

    |> Repo.transaction()

    |> case do

      {:ok, %{intent: failed}} -> {:error, {:payment_failed, failed}}

      {:error, _step, reason, _changes} -> {:error, reason}

    end

  end

  def fail(%TipIntent{} = intent, _failure_code), do: {:error, {:payment_failed, intent}}

  @doc """

  Records a refund and removes the tip's ranking weight.

  The settled receipt stays; a refund appends its own. Totals lose both the

  gross amount and whatever weight the tip carried.

  """

  @spec refund(TipIntent.t(), String.t()) :: {:ok, TipIntent.t()} | {:error, term()}

  def refund(intent, failure_code \\ "refunded")

  def refund(%TipIntent{state: "settled"} = intent, failure_code) do

    refunded_at = DateTime.utc_now()

    Multi.new()

    |> Multi.insert(

      :receipt,

      TipReceipt.changeset(%TipReceipt{}, %{

        intent_id: intent.id,

        kind: "refunded",

        amount_sats: intent.amount_sats,

        failure_code: failure_code,

        occurred_at: refunded_at

      })

    )

    |> Multi.update(

      :intent,

      TipIntent.changeset(intent, %{

        state: "refunded",

        counted_sats: 0,

        exclusion_reason: "refunded"

      })

      |> Ecto.Changeset.put_change(:refunded_at, refunded_at)

    )

    |> add_totals(intent, -intent.amount_sats, -intent.counted_sats, -1)

    |> Repo.transaction()

    |> case do

      {:ok, %{intent: refunded}} -> {:ok, refunded}

      {:error, _step, reason, _changes} -> {:error, reason}

    end

  end

  def refund(%TipIntent{state: state}, _failure_code), do: {:error, {:not_refundable, state}}

  ## Ranking weight

  # How much ranking weight a settled tip earns. Everything that makes a tip

  # unusable as a signal is decided here, once, and recorded on the intent.

  defp counted_sats(%TipIntent{} = intent, settled_at) do

    cond do

      intent.payer_user_id == intent.recipient_user_id ->

        %{sats: 0, exclusion_reason: "self_tip"}

      reciprocal?(intent, settled_at) ->

        %{sats: 0, exclusion_reason: "reciprocal"}

      payer_burst?(intent, settled_at) ->

        %{sats: 0, exclusion_reason: "rate_limited"}

      true ->

        headroom = payer_post_headroom(intent)

        sats = Enum.min([intent.amount_sats, @counted_sats_per_tip, headroom])

        if sats > 0 do

          %{sats: sats, exclusion_reason: nil}

        else

          %{sats: 0, exclusion_reason: "payer_cap"}

        end

    end

  end

  # The recipient already paid this payer recently, so the sats went in a

  # circle and say nothing about the post.

  defp reciprocal?(%TipIntent{} = intent, settled_at) do

    since = DateTime.add(settled_at, -@reciprocal_window_seconds, :second)

    Repo.exists?(

      from i in TipIntent,

        where:

          i.payer_user_id == ^intent.recipient_user_id and

            i.recipient_user_id == ^intent.payer_user_id and

            i.state == "settled" and i.settled_at >= ^since

    )

  end

  defp payer_burst?(%TipIntent{} = intent, settled_at) do

    since = DateTime.add(settled_at, -@payer_burst_window_seconds, :second)

    recent =

      Repo.one!(

        from i in TipIntent,

          select: count(),

          where:

            i.payer_user_id == ^intent.payer_user_id and i.state == "settled" and

              i.settled_at >= ^since

      )

    recent >= @payer_burst_limit

  end

  defp payer_post_headroom(%TipIntent{} = intent) do

    counted =

      Repo.one!(

        from i in TipIntent,

          select: type(coalesce(sum(i.counted_sats), 0), :integer),

          where:

            i.post_id == ^intent.post_id and i.payer_user_id == ^intent.payer_user_id and

              i.state == "settled" and i.id != ^intent.id

      )

    max(@counted_sats_per_payer_post - counted, 0)

  end

  defp add_totals(multi, %TipIntent{} = intent, amount_sats, counted_sats, count) do

    multi

    |> Multi.update_all(

      :post_totals,

      fn _changes ->

        from p in Post, where: p.id == ^intent.post_id

      end,

      inc: [

        tip_sats_total: amount_sats,

        tip_sats_counted: counted_sats,

        tip_count: count

      ]