Skip to Content
Draft v0.2 — this specification is under active design and may change before implementation.
Resolver APIChanges to a market

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:

ProcessWho initiatesWhenYour role
Pre-launch changescreatorbefore the market’s presale or launchyou accept or reject; nothing is applied without your acceptance
Rules requestscreatorwhile the market is live and no proposal is standingadvisory only; you acknowledge, decide independently and may answer
Rules updatesyouwhile the market is live or has a standing proposalyou apply the change directly; it appears in the market’s public rules history

What may change, by phase

FieldBefore presale / launchLiveProposal standing (arbitration)Terminal
title, descriptioncreator proposes, you acceptfrozenfrozenfrozen
Outcome labelcreator proposes, you acceptfrozenfrozenfrozen
Add an outcome (max 8)coming soon (creator proposes, you accept, Melee writes it on-chain)not possiblenot possible—
Remove or reorder outcomesnevernevernever—
endDatecreator proposes, you accept, Melee writes the new timing on-chain (below)frozenfrozen—
timingPolicycoming soon (Melee proposes a policy change, you accept, Melee recomputes timeoutTs)frozenfrozen—
rulescreator proposes, you acceptyou update at will; creator may requestyou update at will; creator may not requestfrozen
Authorities (resolver.resolverAuthority, resolver.proposerAuthority)coming soon (below)frozen on-chainfrozen—

“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.

changeTypeWhat the creator changesAvailable
TitleDescriptiontitle and/or descriptionyes
OutcomeLabelthe labels of existing outcomes (indexes and count unchanged)yes
RulesEditrulesyes
EndDateendDate, and with it the on-chain timing (below)yes
OutcomeAdda new outcomecoming soon
TimingPolicy, AuthorityChangeMelee-initiatedcoming 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 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:

{ "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." }
  • 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:
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 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).

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). 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}/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.
Last updated on