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 | creator | before the market’s presale or launch | you accept or reject; nothing is applied without your acceptance |
| Rules requests | creator | while the market is live and no proposal is standing | advisory only; you acknowledge, decide independently and may answer |
| Rules updates | 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) | 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) | 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) | 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.
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.
{
"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:
{ "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). In the example below, timingPolicy.timeoutOffsetSecs is 86400, so the new endDate
of 2026-09-20 18:00 UTC (1789927200) gives timeoutTs = 1790013600.
{
"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
endDatechanged and recomputetoHashover the fulldefinition, as for any change. - Confirm
timeoutTsequalsdefinition.endDate + definition.timingPolicy.timeoutOffsetSecs, and thatearliestProposalTsis earlier thantimeoutTs. Melee also guarantees thatearliestProposalTsis in the future and, on the current program, at most 7 days beforetimeoutTs. - Check that you can resolve the market on the new schedule: your
EndTimetrigger moves withendDate, andtimeoutTsis 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:
{
"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).
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:
{
"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:
{
"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":
{
"marketPubkey": "9xQe…",
"changeType": "RulesRequest",
"changeId": "…",
"currentVersion": 3,
"currentHash": "9f2a…",
"requestedRules": "…",
"rationale": "The league moved the game to Thursday; please clarify postponement handling.",
"proposedBy": "Creator"
}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 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
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." }decisionisAcceptedorDeclined.reason(≤ 500 characters) is required when you decline and optional when you accept; the creator sees it.Acceptedrecords your answer only. To change the rules as well, send a rules update withchangeIdset to the request: it applies the new version and marks the requestAcceptedin one step.- The answer returns
200with the request asGET /markets/{market}/changeslists it. A request takes one answer: sending the samedecisionandreasonagain returns it unchanged; a different one is409 change_already_decidedwith the recordedstatus. - An unknown
changeIdis404 change_not_found. AchangeIdthat names a change other than a rules request is422 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:
- Fetch the current version with
GET /markets/{market}/definitionand confirmcurrent.definitionHashis what you expect. - Build the new definition by changing only
rules. Every other field must be byte-identical to the current version. - Compute the new
definitionHashover the canonical JSON (RFC 8785). - Call the Melee API:
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:
{ "definitionVersion": 4, "definitionHash": "c0ffee…", "appliedAt": 1788600000 }Rules for rules updates:
- Only
rulesmay change. Any other difference is rejected with422 invalid_change. rationaleis 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,resolveorvoidmust carry the newdefinitionHash; the old one returns409 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
rejectandproposeas usual (see Resolution walk-throughs).
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
AuthorityChangednotifications 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). 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:
{
"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}/definitionif you are unsure which version is current. - Use the current
definitionHashon every resolution action. - Expect the trigger and status payloads to carry the new
definitionVersionanddefinitionHash.