<!-- canonical: https://docs.melee.markets/resolver-api/changes | markdown: https://docs.melee.markets/resolver-api/changes.md | index: https://docs.melee.markets/llms.txt -->
# Changes to a market you resolve

Once you accept a market, its definition is **versioned**. Every change produces a new version with a new
`definitionHash`, records who initiated it and why, and is visible to traders. No definition field changes
without going through one of the processes on this page. Non-definition fields (images, tags, categories)
are not covered here and change without your involvement.

There are three distinct processes:

| Process | Who initiates | When | Your role |
|---|---|---|---|
| [Pre-launch changes](#pre-launch-changes-creator-initiated) | creator | before the market's presale or launch | you accept or reject; nothing is applied without your acceptance |
| [Rules requests](#rules-requests-while-live-creator-initiated) | creator | while the market is live and no proposal is standing | advisory only; you acknowledge, decide independently and may answer |
| [Rules updates](#rules-updates-resolver-initiated) | **you** | while the market is live or has a standing proposal | you apply the change directly; it appears in the market's public rules history |

## What may change, by phase

| Field | Before presale / launch | Live | Proposal standing (arbitration) | Terminal |
|---|---|---|---|---|
| `title`, `description` | creator proposes, you accept | frozen | frozen | frozen |
| Outcome `label` | creator proposes, you accept | frozen | frozen | frozen |
| Add an outcome (max 8) | coming soon (creator proposes, you accept, Melee writes it on-chain) | not possible | not possible | — |
| Remove or reorder outcomes | never | never | never | — |
| `endDate` | creator proposes, you accept, Melee writes the new timing on-chain ([below](#end-date-changes)) | frozen | frozen | — |
| `timingPolicy` | coming soon (**Melee** proposes a policy change, you accept, Melee recomputes `timeoutTs`) | frozen | frozen | — |
| `rules` | creator proposes, you accept | **you update at will**; creator may request | **you update at will**; creator may not request | frozen |
| Authorities (`resolver.resolverAuthority`, `resolver.proposerAuthority`) | coming soon ([below](#authority-changes)) | frozen on-chain | frozen | — |

"Before presale / launch" is the window in which the on-chain market is still configurable. Melee enforces
these windows; a change outside its window is rejected with `change_window_closed`.

## Pre-launch changes (creator-initiated)

Before the market's presale or launch, its creator can propose a change in the Melee UI. Melee builds the new
definition and its hash and sends you `POST {baseUrl}/change` as a decision. Nothing is applied unless you accept.

| `changeType` | What the creator changes | Available |
|---|---|---|
| `TitleDescription` | `title` and/or `description` | yes |
| `OutcomeLabel` | the labels of existing outcomes (indexes and count unchanged) | yes |
| `RulesEdit` | `rules` | yes |
| `EndDate` | `endDate`, and with it the on-chain timing ([below](#end-date-changes)) | yes |
| `OutcomeAdd` | a new outcome | coming soon |
| `TimingPolicy`, `AuthorityChange` | Melee-initiated | coming soon |

Melee proposes a change only after you acknowledged `live` for the market, and only one change per market waits
for your answer at a time.

```mermaid
sequenceDiagram
    participant U as Creator
    participant M as Melee
    participant R as Resolver
    participant C as Solana
    U->>M: Edit definition before launch
    M->>R: POST change with from and to hashes
    alt you accept
        R-->>M: accepted true with signature
        M->>C: Apply on-chain if the change needs it
        alt write confirmed, or no write needed
            C-->>M: Confirmed
            M->>R: POST applied with success true and the new hash
            R-->>M: acknowledged true with the new hash
            M-->>U: Change applied
        else on-chain write failed
            M->>R: POST applied with success false and the previous hash
            R-->>M: acknowledged true with the previous hash
            M-->>U: Change failed, previous version stands
        end
    else you reject
        R-->>M: accepted false with reason
        M-->>U: Change rejected with your reason
    end
```

`POST {baseUrl}/change` payload. Like every notification, it carries its delivery id in the `X-Melee-Delivery-Id`
header, not in the body; for a pre-launch change that id is the `changeId`.

```json
{
  "marketPubkey": "9xQe…",
  "changeType": "TitleDescription",
  "changeId": "4c1d…",
  "fromVersion": 1,
  "fromHash": "9f2a…",
  "toVersion": 2,
  "toHash": "b7e1…",
  "definition": { "…": "…" },
  "summary": "Changed the title",
  "proposedBy": "Creator"
}
```

Evaluate the full `definition` (not just the summary), recompute `toHash`, and reply within the handshake
timeout with HTTP 200:

```json
{ "accepted": true, "definitionHash": "b7e1…", "signature": "<Ed25519 over melee-accept:v1:{marketPubkey}:{toHash}>" }
```

Sign with the `resolverAuthority` bound to the market. Or reply `{ "accepted": false, "reason": "…" }`. A
timeout, a non-2xx, another `definitionHash` or a signature that does not verify counts as rejection. If you
reject, the definition is unchanged and the creator sees your reason.

### End date changes

An `EndDate` change moves the market's on-chain timing, so its `/change` also carries the timing the market will
have once the change is written: `earliestProposalTs` (when the resolution window opens) and `timeoutTs`. The new
`definition` differs from the current one only in `endDate`.

Both fields are always present on an `EndDate` change. Before launch, `earliestProposalTs` is the planned opening of
the resolution window: the market's planned trading start plus 10 minutes, moved later if needed so that it is at
most 7 days before `timeoutTs` (the current program's limit, see
[Contract versions](/resolver-api/reference#contract-versions)). In the example below, `timingPolicy.timeoutOffsetSecs` is `86400`, so the new `endDate`
of 2026-09-20 18:00 UTC (`1789927200`) gives `timeoutTs = 1790013600`.

```json
{
  "marketPubkey": "9xQe…",
  "changeType": "EndDate",
  "changeId": "7a0e…",
  "fromVersion": 1,
  "fromHash": "9f2a…",
  "toVersion": 2,
  "toHash": "e41c…",
  "definition": { "…identical except endDate…": "…" },
  "summary": "Moved the end date to 2026-09-20 18:00 UTC",
  "proposedBy": "Creator",
  "earliestProposalTs": 1789581600,
  "timeoutTs": 1790013600
}
```

Before you accept:

- Confirm that only `endDate` changed and recompute `toHash` over the full `definition`, as for any change.
- Confirm `timeoutTs` equals `definition.endDate + definition.timingPolicy.timeoutOffsetSecs`, and that
  `earliestProposalTs` is earlier than `timeoutTs`. Melee also guarantees that `earliestProposalTs` is in the
  future and, on the current program, at most 7 days before `timeoutTs`.
- Check that you can resolve the market on the new schedule: your `EndTime` trigger moves with `endDate`, and
  `timeoutTs` is the new on-chain deadline.

Sign `melee-accept:v1:{marketPubkey}:{toHash}` exactly as for any change. The signature covers the definition
hash; the timing fields are what Melee will write on-chain for that definition.

When you accept, the change becomes `Accepted`: Melee writes the new timing on-chain, and the definition you are
bound to stays the previous version until the write lands. Melee has 5 minutes from your acceptance to send the
write, plus a 5-minute grace after its last attempt for it to land. You then receive `applied`, with
`success: true` once the write is confirmed, or `success: false` if it failed (below). The market cannot launch
while the change is `Accepted`.

**Applied.** Once the change is in effect (immediately for `TitleDescription`, `OutcomeLabel` and `RulesEdit`,
after `confirmed` commitment for an `endDate` move) you receive `POST {baseUrl}/applied`:

```json
{
  "marketPubkey": "9xQe…",
  "changeId": "4c1d…",
  "changeType": "TitleDescription",
  "definitionVersion": 2,
  "definitionHash": "b7e1…",
  "success": true,
  "outcomes": [],
  "signatures": []
}
```

Reply `{ "acknowledged": true, "definitionHash": "b7e1…" }`. `outcomes` stays empty until outcome additions are
available; an outcome add will list the new outcome with its address, plus an `outcomeSetHash` over all
outcomes, to verify the same way as at launch (see [Verifying the definition](/resolver-api/definition)).

For an `EndDate` change, a successful `applied` carries the new version and hash, the transaction signature of
the on-chain write in `signatures`, the timing now on-chain, and an empty `outcomes`:

```json
{
  "marketPubkey": "9xQe…",
  "changeId": "7a0e…",
  "changeType": "EndDate",
  "definitionVersion": 2,
  "definitionHash": "e41c…",
  "success": true,
  "outcomes": [],
  "signatures": ["5Kq…"],
  "earliestProposalTs": 1789581600,
  "timeoutTs": 1790013600
}
```

Acknowledge with the new hash: `{ "acknowledged": true, "definitionHash": "e41c…" }`.

If `success` is `false` the on-chain write failed and the previous version still stands. The payload carries the
previous version and hash, a `reason`, and empty `outcomes` and `signatures`:

```json
{
  "marketPubkey": "9xQe…",
  "changeId": "7a0e…",
  "changeType": "EndDate",
  "definitionVersion": 1,
  "definitionHash": "9f2a…",
  "success": false,
  "reason": "The change could not be written on chain: the transaction was refused. The previous version stands.",
  "outcomes": [],
  "signatures": []
}
```

Acknowledge with the previous hash: `{ "acknowledged": true, "definitionHash": "9f2a…" }`.

`applied` is a notification: it is retried until you acknowledge, and the market cannot launch while an
`applied` for it is unacknowledged. An acknowledgement with any other hash, or `acknowledged: false`, also holds
the launch until Melee resolves it with you. From acknowledgement on, the `definitionHash` in `applied` is the one
you must send with `propose`, `resolve` and `void`.

## Rules requests while live (creator-initiated)

Once a market is live, the creator can no longer change the rules. They can only **ask you**. Melee forwards the
request as `POST {baseUrl}/change` with `changeType: "RulesRequest"`:

```json
{
  "marketPubkey": "9xQe…",
  "changeType": "RulesRequest",
  "changeId": "…",
  "currentVersion": 3,
  "currentHash": "9f2a…",
  "requestedRules": "…",
  "rationale": "The league moved the game to Thursday; please clarify postponement handling.",
  "proposedBy": "Creator"
}
```

```mermaid
sequenceDiagram
    participant U as Creator
    participant M as Melee
    participant R as Resolver
    U->>M: Request a rules clarification
    M->>R: POST change with changeType RulesRequest
    R-->>M: 202 received
    M-->>U: Request delivered to the resolver
    Note over R: You decide independently, on your own timeline
    alt you agree, in whole or in part
        R->>M: POST /markets/{market}/changes with RulesEdit and changeId
        M-->>R: new version and hash
        M-->>U: Request Accepted, rules updated
    else you decline
        R->>M: POST /markets/{market}/changes/{changeId}/decision Declined with reason
        M-->>U: Request Declined, with your reason
    end
```

Your only obligation is to reply `202` (empty body) promptly. Nothing is applied and no signature is needed.
If you agree with some or all of the request, make the change yourself with a
[rules update](#rules-updates-resolver-initiated) and name the request in its `changeId`. Answering is optional
but recommended: the creator sees your answer on the market, while a request you have not answered stays
`Received` in `GET /markets/{market}/changes`. Creators cannot request rules changes while a proposal is
standing; Melee directs them to your dispute process instead.

### Answering a rules request

```http
POST /api/resolver/v1/markets/9xQe…/changes/{changeId}/decision
Content-Type: application/json

{ "decision": "Declined", "reason": "The rules already say a postponed game resolves on the rescheduled date." }
```

- `decision` is `Accepted` or `Declined`. `reason` (≤ 500 characters) is required when you decline and optional
  when you accept; the creator sees it.
- `Accepted` records your answer only. To change the rules as well, send a rules update with `changeId` set to
  the request: it applies the new version and marks the request `Accepted` in one step.
- The answer returns `200` with the request as `GET /markets/{market}/changes` lists it. A request takes one
  answer: sending the same `decision` and `reason` again returns it unchanged; a different one is
  `409 change_already_decided` with the recorded `status`.
- An unknown `changeId` is `404 change_not_found`. A `changeId` that names a change other than a rules request
  is `422 invalid_change` (`field: "changeId"`).
- You can answer at any time while the market is yours, also after it ended.

## Rules updates (resolver-initiated)

**This is your responsibility.** Between launch and final resolution you own the rules. If the rules need a
clarification for you to resolve the market correctly, you update them. Melee never edits the rules of a live
market on your behalf, and the creator cannot.

When you may update: while the market is **live** or **has a standing proposal** (arbitration). Not before
launch (pre-launch rules are agreed with the creator through acceptance and pre-launch changes) and not after
the market is resolved or voided.

How:

1. Fetch the current version with `GET /markets/{market}/definition` and confirm `current.definitionHash` is
   what you expect.
2. Build the new definition by changing **only** `rules`. Every other field must be byte-identical to the
   current version.
3. Compute the new `definitionHash` over the canonical JSON (RFC 8785).
4. Call the Melee API:

```http
POST /api/resolver/v1/markets/9xQe…/changes
Idempotency-Key: 3b9d…
Content-Type: application/json

{
  "changeType": "RulesEdit",
  "definition": { "…full definition with the new rules…" },
  "definitionHash": "c0ffee…",
  "rationale": "Clarified that a postponed game resolves on the rescheduled date within the season.",
  "changeId": "…"
}
```

`changeId` is optional: set it when the update answers a creator's rules request on this market that you have
not answered yet (otherwise `422 invalid_change`, `field: "changeId"`). The request becomes `Accepted` with this
update; if it was answered in the meantime, the update is not applied and returns `409 change_already_decided`.

Melee verifies that only `rules` differs, recomputes and checks the hash, and applies the change immediately
as the next version:

```json
{ "definitionVersion": 4, "definitionHash": "c0ffee…", "appliedAt": 1788600000 }
```

```mermaid
sequenceDiagram
    participant R as Resolver
    participant M as Melee
    participant U as Creator
    participant T as Traders
    R->>M: GET definition for market
    M-->>R: current version and hash
    R->>R: Change rules only, compute new hash
    R->>M: POST changes with RulesEdit, definition, hash, rationale
    M->>M: Verify only rules changed, verify hash, write version
    M-->>R: new version and hash applied
    M->>U: Rules history shows the new version with your rationale
    M->>T: Rules history shows the new version with your rationale
```

Rules for rules updates:

- **Only `rules` may change.** Any other difference is rejected with `422 invalid_change`.
- **`rationale` is required** (≤ 500 chars) and is shown to traders verbatim alongside the change.
- **Applied on receipt.** There is no creator approval and no second call. Your request is the evidence.
- **You are held to the new version.** Your next `propose`, `resolve` or `void` must carry the new
  `definitionHash`; the old one returns `409 definition_mismatch`.
- **Every change is public.** The market page shows the full rules history: version, timestamp, who changed
  it (you or the creator), the rationale, and the before/after text.
- **No undo.** To revert, submit another rules update.
- **Outside the window** (before launch, or after terminal) the call is rejected with `409 change_window_closed`.
- If a proposal is standing, updating the rules does not clear the proposal. If the clarification changes your
  intended outcome, use `reject` and `propose` as usual (see [Resolution walk-throughs](/resolver-api/lifecycles)).

Use this process sparingly and for clarifications. Traders committed funds against the rules as they stood, and
Melee reviews rules-update patterns as part of the verification badge.

## Authority changes

> **Coming soon.** Until then Melee sends no `AuthorityChanged` notifications and runs no authority change
> rounds: if a market's on-chain keys no longer match the definition you accepted, Melee voids it
> (`AuthorityDrift`, see [Platform void](/resolver-api/lifecycles#platform-void)). This section describes the
> process as it will work.

Your keys are part of the hashed definition (`resolver.resolverAuthority`, `resolver.proposerAuthority`), so
the acceptance you signed names the exact keys bound to the market. Before launch, the market creator can
rotate the market's proposer key on-chain. If that happens on a market you accepted, the on-chain keys no
longer match the definition you signed, and the market **cannot launch** until the mismatch is resolved. You
receive `POST {baseUrl}/lifecycle` with `event: "AuthorityChanged"`, and Melee either reverts the key or sends
you `POST {baseUrl}/change` with `changeType: "AuthorityChange"`, an ordinary change round whose new
definition differs from the current one only in the `resolver` keys:

```json
{
  "marketPubkey": "9xQe…",
  "changeType": "AuthorityChange",
  "fromVersion": 1,
  "fromHash": "2204…",
  "toVersion": 2,
  "toHash": "8b1e…",
  "definition": { "…identical except resolver.proposerAuthority…" },
  "summary": "proposerAuthority rotated by the creator",
  "rationale": "Our previous proposer key was held by a contractor whose engagement ended; rotating to an in-house key.",
  "proposedBy": "Melee"
}
```

`rationale` is the creator's own explanation, optional, at most 500 characters, passed to you verbatim. It is
present when the creator rotated the key through Melee (the normal path), and absent when the creator signed
the rotation directly on-chain, because Melee then has nothing to relay. There can be legitimate reasons to
rotate a proposer key before launch; weigh the rationale as you would any other change. No rationale, or one
you do not find convincing, is grounds to reject.

Recompute `toHash` from the definition as for any change. Reply exactly as for any change, signing
`melee-accept:v1:{marketPubkey}:{toHash}` with the `resolverAuthority` **currently bound to the market**
(`definition.resolver.resolverAuthority` of the `fromVersion`). Reject unless the new keys are yours; a
rejected authority change leaves the market unable to launch until Melee reverts the on-chain key.

## After any change

- Re-fetch `GET /markets/{market}/definition` if you are unsure which version is current.
- Use the current `definitionHash` on every resolution action.
- Expect the trigger and status payloads to carry the new `definitionVersion` and `definitionHash`.
