An optimistic oracle (OO) that can record any verifiable truth or data onto a blockchain 🔮

UMA is an optimistic oracle and dispute arbitration system that securely allows for arbitrary types of data to be brought onchain. UMA’s oracle system provides verified onchain data for projects including:

1. Crosschain bridge

2. Prediction markets

3. Insurance protocols

4. Custom derivatives

UMA's optimistic oracle (OO) is designed to be modular and extensible with focus on building real-world use cases. Two main versions of the optimistic oracle (OO) are currently live: OOv2 and OOv3. Choosing the right one depends on your use case.

Core Concepts

Learn the fundamentals of UMA's optimistic oracle.

Correct Oracle for Your Use Case

UMA offers OOv2 and OOv3. Based on your idea and product, let's learn which one fits your use case best:

We understand that your product needs can be complex and would require a larger discussion on which optimistic oracle version to use. Feel free to reach out to us and get help.

Developer Quickstart

Having decided the correct optimistic oracle for your use case, let's now dive deeper into how you can ship apps powered by verifiable onchain truth using UMA's optimistic oracle.

Community

The UMA token secures UMA’s optimistic oracle through decentralized governance and economic guarantees against corruption. Token holders vote on upgrades, price requests, and disputes, earning rewards for honest participation.

UMA Improvement Proposals (UMIPs) are design documents used to propose changes to the UMA ecosystem. They are an important part of UMA's governance processes.

The UMA DAO accepts proposals for onchain actions that require tokenholders approval. An example would be a request for funding from the UMA treasury.

Resources and Support

We request all community members and developers to and gain instant help on any issues they face while voting or submitting proposals to UMA.

You can .

The security of our protocol is extremely crucial. If you notice any bugs in the protocol, . You can also find details of our .

This section showcases different design patterns for building contracts that integrate with the UMA Optimistic Oracle (OO). These include:

• A simple deposit box to showcase the basic OO request lifecycle.

• An event based prediction market. In this example, settlement requests are submitted at the time of contract deployment, and the OO proposer network is used as a decentralized keeper service that identifies when settlement events happen and propose the outcomes.

• An , where an integrating contract handles proposals and state management, and only uses the OO when proposal verification is needed or a dispute is filed.

May 8, 2025

Using a token that allows backlisting (e.g. USDC) as your currency opens up a griefing vector that integrators should be aware of.

The and functions allow the caller to set any address as the proposer and disputer that will receive payouts if their proposal/dispute is correct upon settlement. If a bad actor calls both and and specifies a blacklisted address for repayment, the function will revert and cause the request to be frozen unless the address is unblacklisted. This costs the malicious user 2 bonds and does not result in any gain, but freezing the request could cause issues for the integrator.

To avoid this, integrations that use tokens with blacklisting functionality should ensure that their admins can call a function that ignores the frozen request and creates a new OOV2 request. In this way they can prevent a frozen request from having any negative consequences to their protocol.

Risk Labs currently provides gas rebates for voters who have staked 1000 or more UMA to encourage more community members to participate in securing the Optimistic Oracle.

• Rebates cover the gas cost for commit and reveal transactions and are denominated in ETH.

• Voters must have at least 1000 UMA staked at the start of the commit period for that voting period's commit and reveal transactions to be rebated.

• Commited votes must be revealed to be rebated.

• If a voter commits more than once on a dispute, only the first commit will be rebated.

• If a delegate address is used to vote, the rebate will be sent to the delegate address.

• Rebates are calculated for one calendar month and are sent out within the first half of the following month. Announcements are made in the UMA Discord at the time each rebate is sent out.

The Voterdapp contains a "Discussion Summary" tab with an LLM summary of Discord comments on the vote. The summary removes duplicate arguments across all comments to give voters an overview of all arguments which is useful for long or spammed comment threads. The summary does not fact check comments, add additional arguments, or give voting recommendations.

Voters should always verify all arguments included in the summaries with their own research. The raw comments are also provided in the "Discord Comments" tab so voters can review them against the summary in case of LLM error.

Using a token that allows backlisting (e.g. USDC) as your assertTruth currency opens up a griefing vector that integrators should be aware of.

The assertTruth and disputeAssertion functions allow the caller to set any address as the asserter and disputer that will receive payouts if their assertion/dispute is correct upon settlement. If a bad actor calls these functions and specifies a blacklisted address for repayment, the settle function will revert and cause the request to be frozen unless the address is unblacklisted. This costs malicious users their bonds and does not result in any gain, but freezing the assertion could cause issues for the integrator.

Integrations that use tokens with blacklisting functionality should ensure that they have a way to manage frozen assertions (e.g. an admin function that can ignore a frozen assertion) without negatively affecting their integration.

Support for oSnap will be deprecated on December 15th, 2025. After this date, oSnap will not be able to execute transactions from your DAO’s Safe treasury.

oSnap integrations should take the following steps to prepare:

• Ensure their Safe signers are prepared to sign and execute any necessary DAO transactions

• Disable oSnap on all DAO treasuries by following these steps: https://docs.uma.xyz/developers/osnap/disabling-osnap

The ManagedOptimisticOracleV2 contract is modified version of the OptimisticOracleV2 intended to be deployed for a single integration. It allows the integration to designate a request manager address that can set a default proposer whitelist and easily manage an existing request's bond size, liveness and proposer whitelist before the request has been proposed.

UMA's Optimistic Oracle allows contracts to quickly request and receive data information. The Optimistic Oracle acts as a generalized escalation game between contracts that initiate a price request and UMA's dispute resolution system known as the Data Verification Mechanism (DVM). Prices proposed by the Optimistic Oracle will not be sent to the DVM unless it is disputed.

If a dispute is raised, a request is sent to the DVM. All contracts built on UMA use the DVM as a backstop to resolve disputes. Disputes sent to the DVM will be resolved within a few days - after UMA tokenholders vote on what the correct outcome should have been.

Optimistic Oracle

The first part of UMA's oracle system is the Optimistic Oracle. This is a layer that is designed to optimistically verify pieces of data quickly. It is secured by the UMA DVM, because disputes can be escalated from the Optimistic Oracle layer to the DVM for dispute arbitration. The main lifecycle of the OO looks like this, and is detailed in the Asserter and Disputer rows within the diagram above.

Risk Labs manages the default proposer whitelist for Polymarket's ManagedOptimisticOracleV2 contract. The current whitelist can be viewed and is subject to updates and changes in guidelines. Polymarket, as the request manager for the contract, may also change an unproposed request’s proposer whitelist at any time.

Current Proposer Whitelist Criteria

Proposer addresses must meet the two below criteria over the last 6 months:

• 5 or more Polymarket proposals on OptimisticOracleV2 or ManagedOptimisticOracleV2

Verifying Proposals

After transactions have been requested for execution, the challenge period begins. The challenge period length is set by the oSnap Safe module advanced settings. Invalid requests must be disputed within the challenge period. oSnap requests can be reviewed in the 's Verify tab.

After selecting a request, a sidebar will show additional request details including the bond amount, when the challenge period ends, a dispute button (when a wallet is connected), a link to the corresponding Snapshot proposal, the oSnap rules that the request should be reviewed against (including minimum quorum and voting period for the Snapshot proposal), and links to relevant block explorer pages.

Requirements:

• The below steps propose a Safe transaction to disable oSnap. Transactions can only be proposed to a Safe by that Safe's Signers or Proposers. You can view these roles on your Safe's settings page.

• Executing the proposed Safe transaction requires your minimum number of Signers to sign the transaction and one Signer to execute the transaction.

Steps:

Internal Learning Sessions

1. Go to the , if you are disputing proposals on a live network like Ethereum, Optimism, or Polygon, or go to the if you are disputing test data on Görli. Disputes will be resolved by the if you are on a live network, or by a mock oracle if you are on Görli (see Resolving Disputes).

2. Locate proposals under the Proposals tab for outstanding proposals that are within the challenge window and can be disputed.

3. Click on the proposal you want to dispute.

Prerequisites

Before getting into the specifics of how to verify proposals from the Optimistic Oracle, please make sure to go through the following resources to understand how UMA works:

As of December 8th, 2025. is the intended default identifier to be used with OOV3. The original identifier will be deprecated as of December 15, 2025. These identifiers have teh same specifications and the change is only to break support for deprecated projects.

Please note: after these changes do not use the following OOV3 functions:

• the assertTruthWithDefaults function will always revert as it hardcodes in the ASSERT_TRUTH identifier

• the defaultIdentifier public constant variable will return the deprecated ASSERT_TRUTH identifier

Viewing, proposing and disputing ManagedOptimisticOracleV2 requests on the Oracle Dapp is the same as other OptimisticOracleV2 requests except for the following differences:

• If your connected address is not on the request's proposer whitelist, the propose button on the request's sidebar will be disabled.

• The request's proposer whitelist is displayed under the "More Information" heading at the bottom of the request sidebar.

Links

You can keep up to date with what is happening with UMA across our various social media platforms and community resources:

Risk Labs/UMA protocol no longer actively supports or improves:

• The

• The

These contracts are open-source code, and anyone is free to use, improve, or fork the code. However note that for these contracts to be safe, it requires a robust system of well capitalized off-chain watchers (liquidator & disputer bots) to continually check that positions are appropriately collateralized, or that positions are not being liquidated unfairly. Anyone using this code in production must ensure that there are well-capitalized liquidators and disputers running at all times; failure to do so could result in a loss of all locked funds. Risk Labs does not and will not run liquidators for these contracts, nor does it give any security assurances about any EMP or Perp contracts. As always, UMA protocol and Risk Labs will continue to support proposed addition or request of price identifiers for general use including within EMP/Perp contracts.

• Read through the vote Description under the Details tab. Carefully review how the vote should resolve and if provided, the timing of when the request can resolve and any listed sources.

• Review the Timestamp under the Details tab. This is the point in time at which the vote should be evaluated.

• The vote Discussion tabs lists comments from the UMA Discord with arguments, resources, and suggested votes that may be helpful. However, some commenters may try to influence the vote for their own profit. Always ​independently verify​ any claims before relying on them.

This section showcases different design patterns for building contracts that integrate with the UMA Optimistic Oracle v3. These include:

• A showcasing the simplest possible OOv3 integration contract.

• Building example contracts:

Proposing and disputing ManagedOptimisticOracleV2 requests is largely the same as OptimisticOracleV2 requests with the following differences:

Adding the ManagedOptimisticOracleV2 Addresses

Programmatic proposers and disputers will be used to listening for OptimisticOracleV2 events and sending proposing and disputing transactions to these addresses. To add support to new ManagedOptimisticOracleV2 deployments, programmatic proposers and disputers will have to add these new deployment addresses to their bot configs.

Note: the first ManagedOptimisticOracleV2 deployment is managed by Polymarket and can be found .

UMA Improvement Proposals (UMIPs) are design documents used to propose changes to the UMA ecosystem. UMIPs are intended to be the primary mechanism for proposing new features, collecting community input on an issue, and for documenting the design decisions that have gone into the UMA protocol.

UMIPs are a convenient way to track the progress of an implementation. Examples of common UMIPS include adding a new price identifier or collateral currency to be supported by the DVM. UMIPs are presented to UMA tokenholders for voting through the voting dapp to determine whether they will be accepted or rejected.

UMIPs need to provide a concise technical specification of the feature and a rationale for the feature. They are modeled after EIPs and ZEIPs. See here for an EIP template and ZEIP template.

If the dispute is on a live network, it will be resolved by the DVM on Ethereum, and the results returned within 48-72 hours (depending on when the dispute was raised during the DVM voting cycle).

If you are testing the dispute flow on Görli, you will need to manually resolve the dispute through the Mock Oracle. This contract stands in for the DVM on Görli and allows you to manually return your own values for testing purposes.

1. Go to the Mock Oracle contract on Görli Etherscan.

2. Click 'Write Contract.'

3. Click 'Connect to Web3' to connect your wallet.

4. Click 'OK' on the pop-up that warns you that writing to contracts on Etherscan is a beta test feature.

5. Connect through your wallet interface, and switch networks to Görli if necessary.

6. Click pushPrice to see the parameters you will need to enter.

7. Enter the original request's identifier, time, and ancillaryData, and enter the value you want to return for price.

8. Click 'Write' and submit the transaction.

9. Depending on how the contract you are testing was written, you may need to call settleAndGetPrice from your contract to the Optimistic Oracle contract to get the value returned from the mock oracle, or you may be able to call settle on the Optimistic Oracle and have your contract automatically receive and handle the return value with a priceSettled callback function.

Every request to UMA's Optimistic Oracle includes bond and liveness settings that specify the size of the bond that proposers (and disputers) are required to post, the token used for bonding, and the liveness window, which is the challenge period during which a proposal can be challenged.

The minimum bond is the same as final fee for Optimistic Oracle V2 (OOV2) or can be queried by calling getMinimumBond(token) for Optimistic Oracle V3 (OOV3). The default liveness window is two hours. For many cases, you may want to customize these values. The primary reason to increase the bond size or challenge window is to increase your security for complex requests or requests that could move large amounts of money.

How to think about proposer and disputer bonds

In most cases, you will want to set a bond higher than the minimum. The reason for this is that the bond provides a financial incentive for disputers to dispute invalid proposals. Disputers receive half of the proposer bond in the case of a successful dispute in the OOV3. For the OOV2, it's half of the excess above the final fee.

The part of the bond that doesn't go to the disputer in a successful dispute goes to the UMA Store contract. The reason the disputer does not get the full amount is to prevent a malicious proposer from making a bad proposal and then front-running an honest disputer to dispute themselves if they get caught.

Example bond payouts (OOV3)

As an example, imagine an application that requires a 10,000 USDC bond to assert a claim via OOV3.

To make an assertion, a proposer must post a 10,000 USDC bond, which they will get back after the liveness window if the assertion is not disputed. To make a dispute, a disputer must also post a 10,000 USDC bond.

If the disputer wins, they receive 15,000 USDC (10,000 USDC disputer bond + 5,000 USDC from the excess proposer bond) and the Store receives 5,000 USDC.

If the proposer wins, they receive 15,000 USDC (10,000 USDC proposer bond + 5,000 USDC from the disputer bond) and the Store receives 5,000 USDC (half of the disputer bond).

Higher or lower bonds?

If data received from the oracle could potentially move large amounts of value, you may want to set a higher bond to make it more costly for an attacker to attempt to steal funds through a false proposal. (Remember that the proposer will lose their entire bond if they are disputed and found to be incorrect.)

The tradeoff to setting a higher bond is that it may be more difficult to run a project that requires frequent proposals, since good proposers will have funds locked up for at least the length of the challenge window. Another tradeoff is that a very high bond may make it difficult for disputers to post bonds to challenge bad proposals. Remember also that disputers will lose their bond if they are incorrect, so the disputer has a capital cost and a risk of loss.

Before launching your contract, you should think about who you expect to be proposers and disputers, whether they have adequate access to capital, how much value the oracle is securing, how many requests you expect to make in a given day, and whether you should add a proposer reward (to incentivize independent proposers to take on the capital cost and risk of proposing answers to your requests).

There are no exact answers to how high or low your bond should be, although it is almost always a good idea to set a bond that is larger than the final fee so that disputers have an incentive to dispute bad proposals.

How to think about liveness

The liveness period is the challenge window where disputers can dispute a proposal, and is another knob you can turn to increase security (while accepting UX trade-offs).

A typical challenge period is two hours, which is usually plenty of time for disputers to recognize and dispute bad proposals. In some cases, you may want to increase the length of the challenge period. A classic example is an insurance contract, since insurance contracts usually have these qualities:

1. Large amounts of value are at stake.

2. Payouts are rare.

3. Proposals and disputes require a greater amount of thought and consideration.

4. Payouts are not very time sensitive, and a long delay (even a day or more) to allow proposers and disputers to think through the situation will not seriously inconvenience users.

You may want to consider a two-hour challenge window in these situations:

1. Requests happen frequently and proposers and disputers will need to reuse their capital regularly for bonding.

2. The dollar value secured by a request is lower.

3. The request is easy to reason about (and proposals and disputes could potentially be automated).

4. Users are sensitive to the settlement time.

At this time, it is generally not recommended to set a challenge window shorter than two hours.

If your users are very sensitive to settlement time, you may want to consider a smart contract architecture that allows a particular type of user to fully insure a piece of data that is acted on instantly, and then waiting to be reimbursed after the challenge window. Think of this user as a "designated waiter," who is probably compensated in some way.

A good example is the in the Across protocol. Users of the Across bridge receive their funds almost instantly, because a relayer sends them funds on the receiving chain and then submits for reimbursement from the protocol, and has to wait for several hours for their relay to be bundled with other relays, proposed, and then settled after the challenge window.

In this case, the UX for most users is excellent (nearly instant transfers) but the protocol is still secured by a long challenge window that is absorbed by a less time sensitive user type (the relayer) who is paid fees for their trouble.

The UMA token is primarily a governance token used to contribute to UMA protocol decisions, such as voting on UMA Improvement Proposals (UMIPs), price requests, and disputes made to UMA's Data Verification Mechanism (DVM).

Governing the UMA ecosystem

The UMA token is an integral part of the UMA ecosystem as it guarantees the economic security of UMA smart contracts and its oracle system. The objective of the UMA token is to enable the optimistic oracle to remain secure utilizing a fully decentralized and permissionless method.

UMA's DVM is designed with an economic guarantee around the cost it would take to corrupt the oracle and the profit someone would receive. The DVM ensures the price to obtain 51% of UMA tokens is greater than the profit from corrupting the DVM, as measured by the collateral stored in UMA's financial contracts. This is achieved through an inflationary reward (currently 0.05% of total network token supply), distributed pro-rata by stake to voters who participate and vote correctly. As long as there is an honest majority, voters will vote correctly.

As the total value of collateral locked in UMA grows, the UMA token is required to increase in value to ensure the security of the DVM. To ensure this inequality holds, the DVM may charge fees to financial contracts which the DVM would use to buy UMA tokens.

Voting

The UMA voting process requires tokenholders to commit and reveal their votes in two separate stages. Each stage is open for 24 hours, so each voting period is 48 hours.

• UMA Tokenholders can discuss their votes in the #voting channel of the before voting

• UMA tokenholders can use the to vote on protocol decisions

Examples of governance proposals include:

• Approving new and

• Price requests and disputes

• Upgrading the core DVM protocol and / or modify DVM parameters

• Registering and de-registering contract templates

This tutorial describes how to propose answers to data requests. The data could be anything from token prices, to who won a basketball game, to whether an optimistic governance action is valid.

Step 1: Go to the Optimistic Oracle dApp, if you are answering requests on a live network like Ethereum, Optimism, or Polygon, or go to the Testnet dApp if you are answering requests (probably your own) on Goerli.

Step 2: Locate requests under the Requests tab for outstanding requests.

Step 3: Click on the request you are interested in proposing data for.

Step 4: Click the 'Connect wallet' button in the top right corner and go through the steps to connect your wallet. Confirm you are on the same network as the data request.

Step 5: Before proposing, confirm the details of the request and ancillary data to ensure you are proposing accurate data. You may also want to check the instructions in the for the identifier.

Step 6: Once you are sure of the proposed value and connected to your wallet, input the value and click the 'Submit Proposal' button.

Step 7: Confirm the transaction details through your wallet provider. After confirming, the proposal will be sent!

Optimistic Oracle

The "Optimistic Oracle" (OO) allows contracts to quickly request and receive price information. Unlike mechanically restrictive price feed oracles, an optimistic oracle can serve any arbitrary data on-chain.

DVM

The “Data Verification Mechanism” (DVM) is the name of the oracle service provided by UMA. The DVM does not provide an on-chain price feed. Instead, it is only used to resolve disputes of liquidations and to settle synthetic token contracts upon expiration.

Parameters of a Long Short Pair (LSP) smart contract:

Financial Product Library (FPL)

The financial product libraries are used to transform the value returned by the price identifier into a final settlement value. Financial product libraries can be applied to create different types of financial contracts and payout functions.

Refer to for a list of deployed financial product libraries for each network. If your desired financial product library is not already deployed, refer for instructions on deploying and verifying your own financial product library contract.

collateralPerPair

The collateralPerPair parameter determines the amount of collateral required to mint each pair of long and short tokens.

• Example: If a contract uses WETH as collateral and the collateralPerPair parameter is set to 0.25 on deployment, each long and short token that is minted would require 0.25 WETH as collateral.

expiryPercentLong

ExpiryPercentLong is used to determine the redemption rate between long and short tokens. ExpiryPercentLong is a number between 0 and 1, where 0 assigns all collateral to the short tokens and 1 assigns all collateral to the long tokens.

UMA Product Types:

Range Tokens

Range tokens enable a DAO to use its native token as collateral to borrow funds. At maturity, if the debt is not paid, the range token holder is instead compensated with an amount of the collateral (the native token) using the settlement price of the native token to determine the number of tokens. This is similar to a tokenized convertible debt structure.

Success Tokens

Success tokens offer an alternative way for DAOs to diversify their treasury and sell tokens to investors in an incentive-aligned way. Success tokens are two financial products wrapped into one token: a set amount of a project token which is combined with a covered call option on that token backed by a set amount of the same token.

KPI Options

Key Performance Indicator (KPI) Options are synthetic tokens that will pay out more rewards if a project’s KPI reaches predetermined targets before a given expiry date. Every KPI Option holder has an incentive to improve that KPI because their option will be worth more. This is intended to align individual token holder interests with the collective interests of the protocol.

The UMA DAO accepts proposals for on-chain actions that require tokenholders approval. An example would be a request for funding from the UMA treasury. The steps to complete a proposal:

Step 1: Post to Discourse

The first step is making a post in the UMA discourse under non-technical UMIPs. The post should outline the key components of a proposal and give the community a chance to submit feedback and recommend changes.

An example submission is Polymarket's Liquidity Mining Program.

Step 2: Snapshot Vote

When the proposal appears ready, a Snapshot vote can be created by the proposer with a 5 day close. Should it receive majority support at the end of 5 days, it will then pass to snapshot for an indicative vote prior to being put to an on-chain vote.

Proposals that require movement of treasury funds require a 4,000 UMA bond to be posted which is returned if the proposal is successful in an on-chain vote of tokenholders.

RiskLabs, the foundation which established UMA, has indicated its willingness to handle the on-chain proposal and cover the bond payment for proposals which attract majority support on a snapshot poll of tokenholders.

Here is the snapshot for .

Step 3: On-chain Vote

After a Snapshot vote has successfully passed, an on-chain vote is held to transfer the funds. If the vote is successful, the funds are transferred to the recipient wallet address.

For a complete list of all current integrations see:

This table includes identifiers that could be useful for new contracts and are likely to be encountered by proposers, disputers, and voters. It does not include identifiers that have been deprecated, identifiers that have fallen out of use, or specific token pairs.

If you need an identifier that is not included in this list, you can for approval. If a price request is made with an identifier that is not on this table, please refer to the canonical on GitHub. The absence of an identifier from this table does not necessarily mean the identifier is not approved, it just means it is not recommended for new contracts.

If you want to use an approved identifier that is not on this list, let us know and we can add the identifier back to this table for easier voter/disputer reference.

This section explains the UMA subgraph and how to interact with it. The UMA subgraph indexes data from UMA contracts over time. It organizes data about tokenholders, contracts, DVM requests, voting, and more. The subgraph updates for each UMA contract interaction. The subgraph runs on protocol’s hosted service and can be openly queried.

UMA has a GraphQL API Endpoint hosted by called a subgraph for indexing and organizing data from the smart contracts. The schema of GraphQL elements available is defined in .

Ethereum Mainnet

This tutorial describes how to vote using the . For context, each voting period is 48hrs. Voting takes 3 steps:

• Commit Vote: the first 24hrs of a voting period allows you to encrypt and commit your vote

• Reveal vote: the second 24hrs of a voting period allows you to decrypt and reveal your vote. Votes are tallied by a DVM smart contract at the end of the reveal period.

What is the YES_OR_NO_QUERY?

The YES_OR_NO_QUERY (UMIP can be read here) is a price identifier intended for plaintext binary questions. Requesters encode their questions in ancillary data. For a full overview of how ancillary data is formatted, refer here.

The YES_OR_NO_QUERY is most typically used by Polymarket today to resolve the outcome of information markets. This can come in the form of asking for the outcome of sports games, a crypto or nft price at a specific point in time or world events among many other things.

Note that this price identifier is often in the form of YES or NO, but could also be in the form of THIS or THAT - ie “did the Lakers or Clippers win the game last night” can work even though it is not really a YES or NO question. The example used in the rest of this document will illustrate how this can be done.

Components of Ancillary Data

From the UMIP:

When converted from bytes to UTF-8, the ancillary data should be a dictionary object containing q (question), p1, p2, p3 and p4 keys and values. p4 is optional and will only apply in certain situations.

Example:

q: title: French Open Final: Djokovic vs. Ruud, description: This market will resolve to "Djokovic" if Novak Djokovic wins the final, or to "Ruud" if Casper Ruud wins the final. res_data: p1: 0, p2: 1, p3: 0.5. Where p1 corresponds to Ruud, p2 to Djokovic, p3 to unknown/50-50,initializer:91430cad2d3975766499717fa0d66a78d814e5c5

The UMIP goes on to note default values for p1, p2, p3 and p4.

• p1 is usually used for “NO” values and defaults to `0` if not explicitly assigned

• p2 is used for “YES” values and defaults to `1` if not explicitly assigned

• p3 is for “UNKNOWN” or “CANNOT BE DETERMINED” and defaults to `0.5` if not explicitly assigned.

• p4 is for situations where the question is expected to eventually be able to be evaluated, but cannot be at this time. An example would be if the outcome to a sports game was asked for, but the game has not yet happened or finished. This will be referred to as the “magic number” and defaults to the minimum int256 value or before e18 scaling: -57896044618658097711785492504343953926634992332820282019728.792003956564819968

Important Note: Polymarket currently uses OptimisticOracleV2. Therefore, the early request should only be used if a proposed value is proposed earlier than the expected event resolution time noted in ancillary data.

For additional context on when the magic number or p3 are expected to be returned, from the UMIP:

p4 is intended to be used for situations where it is not a given that the price request (or contract settlement) should even occur yet. An example of this would be the UMA event-based expiry LSP. A request to settle an event-based expiry LSP can be submitted at any time but if the question can not be resolved yet it should be ignored.

The default p4 value is the minimum int256 value and is used as a "magic number" to indicate that an event-based expiry request is invalid and the contract should continue as normal. For example, if the question is related to a basketball game on January 6th and a settlement request comes in on January 5th, the question can not be resolved yet, and voters should return the p4 value with the magic number to reject the settlement request. This value also moves the decimal place 18 spaces to the left, due to the default behavior of the UMA voting interface to scale input values to 18 decimals. After scaling by the interface, the value will be -57896044618658097711785492504343953926634992332820282019728792003956564819968

Notice that a p3 value would never be returned earlier than the final price request time noted in the ancillary data or the requesting contract's expiration timestamp and a p4 value would never be returned after that point. Consider an unresolvable question like, "Was the weather nice on January 6th, 2022?" If the question was asked on January 7th, 2022, you would return the p3 value. If the same question was asked on January 5th, 2022, you would return the p4 value.

Scaling values

Also noted in the UMIP is the fact that return values are not scaled when referred to in the UMIP or present in ancillary data.

This simply means that if the ancillary data contains “p2:1”, this should really be returned on-chain as 1e18 (not 1 wei). So 1000000000000000000 instead of 1.

All price identifier values are treated this way in the UMA system. The UMA voter dapp and Optimistic Oracle proposer interface both perform this scaling automatically for UMA voters or proposers.

Understanding Question Data

When verifying a proposal, it is important to assess the question data and arrive at their own conclusion for what the return value should be. Here is the example above in the oracle UI:

Key data in the proposal is the identifier, timestamp, and the ancillaryData.

The YES_OR_NO_QUERY identifier tells us which “pricing methodology” we should be referring to. This is best understood by reading the corresponding UMIP. For all price identifiers, the UMIP can be looked up by price identifier name.

The proposed time tells us the timestamp a value was proposed and therefore should be evaluated.

The Additional Text Data above represents the ancillary data and contains the plaintext version of the binary question that a proposer should be evaluating. It is important to read the full text data as it could also contain pricing specifications or data sources that should be used.

In the example, I can see that the question is asking if Novak Djokovic or Casper Ruud wins the French Open Final. It does not specify a data source so I can use a wide array of publicly available information to determine what I think the correct answer should be. Referring to ESPN scores:

I see that Djokovic won and I should continue to read the ancillary data to determine which return value should be used in this scenario.

Ancillary data question:

This market will resolve to "Djokovic" if Novak Djokovic wins the final, or to "Ruud" if Casper Ruud wins the final.

Resolution key:

res_data: p1: 0, p2: 1, p3: 0.5. Where p1 corresponds to Ruud, p2 to Djokovic, p3 to unknown/50-50

Since Djokovic won and p2 corresponds to 1, the proposed value should be p2:1.

Voters/proposers should typically evaluate all price requests independent of the party that has requested the data. But as a validation tool, the requestor can sometimes provide information that will help us verify the values that we are about to propose. As an example, this question was from .

This is one simple example of evaluating a YES_OR_NO_QUERY, but almost all questions follow the same format.

The UMA DVM two-key contract enables you to actively engage in voting using hot keys (private keys stored on machine and used often), but protect your funds with the stronger, and preferable, use of cold keys (private keys stored offline and used rarely). Another way this contract can be used is to delegate voting rights to an EOA, while still maintaining token ownership with a multisig or other ownership structure.

Each two-key contract is a unique smart contract that you deploy. It keeps track of:

• The number of UMA tokens you have deposited into the two-key contract

• The address of your hot wallet; the hot wallet is permissioned to sign transactions and vote in DVM governance

• The address of your cold wallet; only the cold wallet (and importantly, not the voting wallet or any other address) is permissioned to withdraw UMA tokens from the two-key contract

DANGER

If you do not know exactly why you are setting up a 2-Key contract, then you likely do not need one. Deploying the contract is expensive and unnecessary unless you need to vote with separate hot and cold keys.

Voting with a hardware wallet is not a reason that necessitates needing to set up a 2-Key contract. You can likely vote by connecting your hardware wallet to MetaMask or another wallet provider.

If you have any doubt about your need for a 2-Key contract, please ask in the UMA Discord before proceeding.

Prerequisites

• You need ETH in your hot wallet for the initial deployment of the 2-key contract and for submitting all subsequent votes.

• You need ETH in your cold wallet to make the initial UMA token deposit, and also if you ever want to withdraw tokens from the 2-key contract.

Instructions to deploy your own 2-key contract

Connect

Navigate to the UMA voter dApp (vote.umaproject.org) and connect your MetaMask hot wallet. This will be your voting wallet going forward.

Deploy

Click on the gear icon on the far right.

In the modal, click Add Cold Wallet Address

Input your cold wallet address and click Save.

Verify your deployment was correct

The following steps help you verify that your two-key contract was deployed correctly and check that the permissions are held by the correct address.

• Copy the 2-key smart contract address (i.e., DesignatedVoting Escrow Account) from the voter dApp and view it on Etherscan

• Under Read Contract input roleID 0 in function 1. getMember, and click query. Check that the address output matches your cold wallet address.

• Input roleID 1

Voting

To vote with the 2-key contract, you will need to send UMA tokens to it. After sending UMA tokens to the two-key contract address, you can immediately start voting with your hot keys at the voter dApp. This will exclude you from voting with any additional UMA tokens that are in your hot wallet through the voter dApp.

Withdraw tokens

The following steps let you withdraw UMA tokens from the two-key contract using your cold keys. You will have to withdraw and deploy a new two-key contract if you want to designate a new hot key for voting.

• Navigate to your DesignatedVotingContract on Etherscan

• Connect your cold wallet by clicking the “Connect to web3” button

• Use function 11. withdrawErc20

Changing the voter address

To change the voter address for a DesignatedVotingContract, you just need to call resetMember(newAddress) with your cold keys (owner address) and pass in the new address that you wish to use as the voter.

What kind of APY can I expect to receive for staking?

To learn more about how exact APY is calculated, you can refer here.

At a high level though, all UMA voters on average will receive an APY determined by the annual UMA emissions amount divided by the average total UMA staked over the year.

Before the DVM 2.0 upgrade, approximately 18-20mm UMA was voting on average for each vote. If this holds relatively constant, it means that average UMA voter APYs will be approximately 28-32%. This can of course fluctuate on an individual voter basis dependent on voter performance.

How do I maximize my APY?

Maximizing your APY should be simple. To maximize APY you should:

• Remain staked within the system.

• Claim and restake your rewards at times when it makes sense based off balancing your increased stake’s additional future rewards received against gas costs of claiming and restaking.

• Vote consistently and carefully. Incorrect or absent voter stakes are slashed and distributed to correct / participating voters after each voting round.

What is the current UMA voter rewards emission rate?

The UMA emission rate is currently 0.155 UMA/second. This will be distributed pro-rata to all stakers within the UMA system on a per second basis. The UMA emissions rate is controlled by UMA governance and can be updated at any time by a DVM vote.

What is the unstake timer? Why does this exist?

The unstake timer is a set amount of time that a staker must wait before they can execute a request to unstake from the UMA system. With the initial DVM 2.0 upgrade, this unstake timer was set to 7 days.

The unstake timer exists to make the UMA voting system more hardened against attempted manipulation attacks. UMA has always had an assumption that if a malicious attacker could manage to either vote with or bribe a majority of voters to vote incorrectly on a dispute, the UMA token would go to zero in value. This is known as the UMA cost of corruption.

In practice, this is probably not entirely true as markets are not entirely efficient. Attackers could likely dump voted with tokens for some amount of value after a successful attack. Having a required 7 hold period more strongly enforces that UMA’s cost of corruption is enforced by the market if a manipulation attempt is successful.

What kind of things does the DVM vote on?

The Optimistic Oracle & DVM can provide all kinds of different data, from crypto prices, to sports, to verifying if a bridging transaction was valid, with new use cases being added all the time, so its hard to anticipate precisely what you might be asked to vote on, however all questions will be asking something about the state of the world at a particular time, indicated by the timestamp.

How should I determine what I should vote?

There are two primary data sources to assist a voter in determining what value they should vote with.

First, the UMIP that the DVM request references. This will tell you general information about how that question should be answered. The second place to check is the ancillary data of the question. This will provide more context for the question and is likely to include a source, which a link that will take you to a place where that data is likely to be published.

Disputes are also discussed at length in the #voting-chat and #evidence-rationale channels.

Why do I have to commit and reveal votes?

The commit/reveal cycle prevents people from seeing how others have voted by encrypting all initial votes and only decrypting them once all votes are cast. The oracle is built on Schelling Point theory, which indicates that the most likely consensus of non-colluding participants is the truth. By obscuring how other people have voted, this ensures that each tokenholder votes independently.

Can I vote with tokens that haven’t been staked?

No. Only tokens that have been staked can be voted with. If you have already initiated the unstaking process for any or all of your coins, they also will not receive rewards or be able to be voted with. However if you have unstaked coins when a vote starts, you can stake your coins any time up to the end of the commit period, and they will be eligible to vote with.

Can I vote while I am unstaking?

Unstaked tokens cannot vote. This includes tokens that are in the “cooldown period” after an unstake request has been submitted.

Can I cancel an unstake request while it is pending?

You cannot. Unstake requests cannot be canceled once submitted. If you once again wish for those tokens to be staked, you can wait for the unstake period to finish, claim your tokens and restake them.

Can I get someone else to vote on my behalf?

It is possible to delegate your staked UMA in one wallet to a different wallet, allowing voters to keep their UMA on a cold wallet and vote with hot wallet, however there is a 1-1 relationship between voting wallets and staking wallets, therefore it is not possible for one person to vote on behalf of multiple other people.

Do I still get gas rebates?

Yes! Risk Labs will still be continuing with the existing voting gas rebate program.

I still don't know how this works - where can I get help?

Jump into our and ask questions about anything that you are unsure of.

The primary integration point into the UMA ecosystem is the Optimistic Oracle (OO). The OO is an oracle for arbitrary off-chain data which leverages an interactive escalation game between requesters, proposers and disputers and is secured by economic incentives.

This getting started tutorial will show you how to go from 0 to 1 with the Optimistic Oracle by executing the simplest possible request flow. Later in the docs you can find more information on and dig deeper into its mechanism and .

The primary integration point into the UMA ecosystem is the Optimistic Oracle V3 (OOV3). The OOV3 is an oracle for arbitrary off-chain data which leverages an interactive escalation game between asserters and disputers and is secured by economic incentives. It differs from the Optimistic Oracle V2 (getting started can be found ) by being easier to reason about and simpler in integration points.

This getting started tutorial will show you how to go from 0 to 1 with the OOV3 by executing the simplest possible assertion flow. Later in the docs you can find more information on how the OOV3 works and dig deeper into its mechanism and more sophisticated code examples.

Step 1: Install Required Dependencies:

git:

• Documentation: https://github.com/git-guides/install-git

yarn:

• Documentation: https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable

node.js

• Documentation:

• Run the following command to check what version of node you are running: node -v Make sure it is greater than 16.18.0.

redis:

• Documentation:

• Note: Follow the instructions

ts-node

• You can use the following to install globally: npm install -g ts-node

Nvm (optional)

• Documentation:

• Note: Optional, but nvm allows you to easily install and switch between node versions

VS Code (optional)

• Highly recommend using a code editor like VS code.

Step 2: Clone the relayer-v2 repo:

• If using VS code, open the terminal and run the following command:

Step 3: Run Redis

Open a terminal window and run:

Step 4: Environment Variables

• Change the .env.example file to .env

• In line 8 and 9, uncomment either the MNEMONIC or PRIVATE_KEY and input a private key that has no money on it.

  • I used to create a private key to use for the demo but again, do not use one that has any money on it as it is an unnecessary risk.

Step 5: Run the script

The below is an example, however the two changes that need to be made based on the request are:

• REQUEST_TIME=CHANGE_THIS_TO_THE_TIMESTAMP

• I used privateKey for the below, however, if you used mnemonic in your env variables, it should be changed to –wallet mnemonic

Note: The first time you run this, it is going to take a long time.

REQUEST_TIME=1692110627 ts-node ./src/scripts/validateRootBundle.ts --wallet privateKey

When the script finishes running, check the Validation results as shown below. The below shows an example of an invalid bundle as it shows “valid”: false:

Appendix

For additional documentation on Across root bundles, visit:

The UMA DVM is the arbitrator for the Optimistic Oracle and other UMA ecosystem contracts. It facilitates dispute resolution wherein UMA token holders vote in a commit reveal schelling point mechanism. For an overview of how the DVM see here. The DVM has been rebuilt with the new iteration being released in Q1 of 2023.

At a high level, the upgrade adds a new staking and slashing mechanism wherein voters earn a pro-rata share of emissions for staking and are slashed for voting wrong (or not voting). This upgrade also reworks a number of other DVM contracts such as the governor, proposer contract and a new designated voting contract. Finally, this upgrade adds a new emergency recovery mechanism to the DVM that enables admin proposals to bypass the DVM's schelling point oracle system in the event of an emergency. More detail on the individual changes are broken down in the sections that follow.

This doc page outlines some of the changes between DVM 1.0 and DVM 2.0 and some other relevant implementation details.

Mechanism changes & UMA tokenomics update

The DVM2.0 introduces three key changes to how the UMA token interacts with DVM system:

1. Voters now must stake UMA in the DVM to participate in the schelling point and to receive rewards.

2. Voters now earn a pro-rata share of a fixed emission rate simply for staking their tokens. Staking rewards are emitted at a constant rate per block. This means you can work out the overall UMA inflation over time and stakers can easily work out their APY for staking in the system. In comparison to the previous inflation system, the total inflation rate is no longer a factor of the number of votes held by the DVM. The pro-rata share of tokens received by stakers is independent of their voting performance. The emissions rate is set through UMA governance.

3. Voters' staked balances are also now susceptible to slashing. The slashing mechanism redistributes tokens from inactive and wrong voters to the stakers who voted correctly. This hardens the schelling point by adding a more punitive cost function to being wrong. Governance votes are treated as a special price request category where the slashing mechanism is not applied.

Vote Delegation

First class vote delegation support enabling a 1 to 1 relationship between the delegator and delegate wallets. This lets a voter delegate from a secure cold storage wallet to a hot wallet. The hot wallet can commit, reveal and claim and re-stake their rewards but cannot access the underlying stake. If desired, more complex delegation systems (pooled UMA staking with delegate voting etc) can be built on top of this externally to the core UMA contracts.

Emergency recovery system

The DVM 2.0 now has an emergency recovery mechanism where bonded emergency proposals can be executed to short-circuiting and bypass the normal voting mechanism. This enables the DVM to recover from any kind of internal failure mode that could occur (breakage in the commit reveal system, contract issues or other) through a permissionless upgrade flow.

Other system wide changes

There are a number of other changes made, including:

1. Governance proposals now include ancillary data enabling better identifying information to be passed along to voters.

2. Price requests now contain a unique identifier, enabling easier tracking and support in front ends.

3. A number of gas optimizations were made throughout the protocol.

Implementation details

The sections below contain some details on nuanced implementation details of the DVM2.0 system.

Staking APY

Staking rewards (and the associated APY) consists of two discrete components: a) rewards from being staked and b) balance changes from slashing. The net staking APY you receive considers both of these values. Let's consider them separately.

Staking rewards are a pro-rata share of a fixed emission rate, calculated on a per block basis. The rewards you are entitled to, from the last time you claimed, are calculated as follows:

Slashing rewards & penalties at the time of DVM 2.0 launch are designed to be as simple as possible, with the ability to update them at a later point through the use of a Slashing Library. At launch, slashing penalties will be approximately equal to the rewards one would have earned for an estimated stake duration. This has been targeted based off historical DVM 1.0 vote frequency, and means that someone who stakes but does not participate in any votes (or gets all votes wrong) should have their slashed stake and accumulated rewards cancel out for a 0% APY. This amounts to losing 0.1% of your staked amount per vote that is incorrect or missed. Note that each voting round (48 hour commit-reveal cycle) can have multiple votes in it (for example multiple price requests or governance actions). The amount you earn for voting correctly is the voters pro-rata share of the slashing of the incorrect voters. This can be calculated per voter per round as follows:

Then, the total amount slashed per round is the sum of all voters slash for that round:

A voter, who was correct, will then earn a pro-rater share of the totalSlashPerRound as:

A staker's net APY is therefore the sum of their stakingRewards and positiveSlashForCorrectVotePerRound annualized over a 1 year period.

Rolled votes

Under some situations votes can "roll". We define a rolled vote as a vote that was not resolved in one vote round and was moved into the subsequent voting round due to not successfully reaching the two types of needed quorums. These quorums are known as GAT (God Awful Threshold) and SPAT (Schelling Point Activation Threshold).

The GAT within the DVM 2.0 is a constant amount of UMA that must vote on any given vote for it to not roll. In the DVM 1.0, this was set as a percentage of circulating UMA. At the time of DVM 2.0 initial deployment, the required GAT per vote is a constant 5 million UMA.

The SPAT is a new concept from the DVM 2.0. It is a percentage of staked tokens that must vote and agree in order for a vote to not roll. The required SPAT is 65% currently of staked tokens.

If a vote does not satisfy both of these constraints, it will roll.

Vote Deletion

There are certain situations in the DVM 2.0 where voters may want to delete votes. A good example of this would be in the case of spam deletion, where needless price requests are submitted in order by an attacker to try to create some sort of desired slashing conditions.

In the DVM 2.0, votes are deleted once they have rolled a certain number of times. So if voters choose to not vote on the resolution of price requests, and either the GAT or SPAT are not met for a set number of voting rounds, those price requests will become deletable. At the time of DVM 2.0 initial deployment, the number of times a vote is rolled before being deleted is 4.

Below are some sample queries you can use to gather information from UMA contracts.

You can build your own queries using a and enter your endpoint to limit the data to exactly what you need.

Financial Contracts

UMA Contract Lifecycle

UMA's Optimistic Oracle allows contracts to quickly request and receive price information. A request is made when a contract submits the following parameters with a request to the Optimistic Oracle contract:

• identifier: price identifier being requested.

• timestamp: timestamp of the price being requested.

• ancillaryData: additional arguments passed with the price request.

• currency: ERC20 token used for payment of rewards and fees. Must be approved for use with the DVM.

• reward: reward offered to a successful proposer. Will be paid by the caller. Note: this can be 0.

Proposers respond to price requests by referencing off-chain price feeds to submit the price of an asset. In return for their work they will receive a pre-defined proposal reward set by the Requestor. To propose prices, the Proposer is required to stake a proposal bond. In the event that the price information they proposed is disputed and deemed incorrect, the Proposer will lose their bond.

Disputers can refute a price submitted by a Proposer within the proposal liveness period by referencing their own off-chain price feeds. The proposal liveness period is a pre-defined amount of time a proposal can be disputed before the Requestor receives the price of the asset.

If Disputers do not refute the price submitted by the Proposer within the proposal liveness period, the price is sent to the Requestor. If a proposal is disputed, the price will be submitted to UMA’s DVM and resolved after a 48-96 hour voting period.

Integrating with the Optimistic Oracle

We continue to use the contract as an example. The OptimisticDepositBox is a minimal financial contract that allows a user to deposit collateral into a contract and later withdraw their collateral corresponding to a desired USD amount. When the user wants to make a withdrawal, a price request is made to the Optimistic Oracle.

Let's first take a look at the OptimisticDepositBox constructor. Optimistic Oracle price requests require the use of a whitelisted identifier and collateral. The OptimisticDepositBox uses the protocol Finder to discover UMA protocol contracts and call the isOnWhitelist method on the AddressWhitelist and the isIdentifierSupported method on the IdentifierWhitelist contract to confirm both are whitelisted before deployment.

Example arguments used to deploy the contract can be found and tested in the . A whitelisted USDC contract is used for collateral, the Finder and Timer addresses use existing UMA ecosystem contracts that are deployed, and a price identifier that has been contract.

Requesting a Price

A price request is made when the requestWithdrawal is called. A depositor submits the denominatedCollateralAmount to withdrawal and a requestPrice call is constructed with the following arguments and in the :

After price request functionality has been implemented into your contracts, you can test your changes by creating a test in the developer quickstart repo similar to the OptimisticDepositBox test below:

Price Proposals

The code snippets above represent the core functionality for deploying a minimal contract and requesting a price. The next step in the contract lifecycle after a request has been made is a price can be proposed.

is the proposePriceFor function from the Optimistic Oracle contract that is used to propose a price for requests. The price proposal will revert if the parameters do not match an existing price request. For reference, the demonstrates how to call the proposePriceFor method.

Liveness

An important aspect to consider when using the Optimistic Oracle is the liveness period which is the number of seconds a proposal must wait before a price can be resolved and contracts can be settled. A defaultLiveness value is set (currently 7,200) or developers can set a customLiveness value.

To set a customLiveness value with our OptimisticDepositBox example above, we could add line 5 to change the liveness period from 7,200 seconds to 3,600:

Proposal Bond

A proposal bond is a preloaded reward to incentivize price proposals. Similar to the liveness period, a custom bond amount can be set for a price request.

Two important aspects to remember when setting a proposal bond is:

• When making a price request, the caller must approve the contract to transfer the value of the proposer reward for the collateral being used.

• The value corresponds to the collateral decimal value. So setting the reward to 1 for USDC that uses 6 decimals would be 1000000 while an 18 decimal token would be 1.

The below shows an example of setting the proposer bond to 50 USDC (6 decimals):

Settlement

The OptimisticDepositBox contract uses the executeWithdrawal method to settle contracts. It first checks if a price has been resolved by calling the hasPrice method on the Optimistic Oracle which reverts if the request is not settled or settleable. If a price has been resolved, settleAndGetPrice is called.

Security of the platform is our highest priority. All contract code and balances are publicly verifiable, and security researchers are eligible for a bug bounty for reporting undiscovered vulnerabilities.

Audits

OpenZeppelin has performed the following audits on UMA contracts:

• Common and oracle directory contracts: April 28, 2020

Additionally, OpenZeppelin audits incremental upgrades to UMA's contracts on a continuous basis. The continuous audit report can be found .

Bug Bounty Rewards

UMA encourages the community to audit our contracts and security; we also encourage the responsible disclosure of any issues. The bug bounty program is intended to recognize the value of working with the community of independent security researchers and sets out our definition of good faith in the context of finding and reporting vulnerabilities, as well as what you can expect from us in return.

UMA offers substantial rewards for discoveries that can prevent the loss of assets, the freezing of assets, or harm to users.

All rewards will be paid in $UMA, and the amount of compensation will vary depending on bug severity. Reward amounts typically correspond to severity in the following manner.

Severity is calculated according to the risk rating model based on Impact and Likelihood.

Scope

The scope of our bug bounty program includes any and all of UMA's production smart contracts. It does not include known issues with the intended behavior.

In scope

• All UMA, Oval, or Across smart contracts that are deployed to mainnet or are otherwise noted as being applicable.

• Bot or other offchain code to support deployed smart contracts.

Examples of what’s in scope:

• Being able to steal funds

• Being able to freeze funds or render them inaccessible by their owners

Out of scope:

• Issues that have already been submitted by another user or are already known to the UMA team

  • Note: this includes bugs known to the UMA team, but have not been disclosed due to active mitigation efforts.

• Vulnerabilities in contracts built on top of the protocol by third-party developers (such as smart contract wallets)

Submissions

Please email your submissions to .

The submission must include clear and concise steps to reproduce the discovered vulnerability.

Terms & Conditions

If you comply with the policies below when reporting a security issue to us, we will not initiate a lawsuit or law enforcement investigation against you in response to your report.

We ask that you:

• Report any vulnerability you’ve discovered promptly.

• Avoid violating the privacy of others, disrupting our systems, destroying data, or harming user experience.

• Use only to discuss vulnerabilities with us.

• Keep the details of any discovered vulnerabilities confidential until they are publicly announced by Risk Labs.

Public disclosure of the bug or the indication of an intention to exploit it on Mainnet will make the report ineligible for a bounty. If in doubt about other aspects of the bounty, most of the will apply.

Any questions? Reach us via email (). For more information on the UMA platform, check out our and .

All reward determinations, including eligibility and payment amount, are made at UMA’s sole discretion. UMA reserves the right to reject submissions and alter the terms and conditions of this program without notice.

General Questions

How UMA Works

oSnap and DAO Tooling

UMA Participants (Proposers, Disputers, and Voters)

Proposing Data

Disputing Data

Voting

Technical Questions

Recent Optimistic Oracle Upgrades

Security

Compatibility and Limitations

Operational Edge Cases

Building and Integrating with UMA

Governance

Tokenomics

Community and Ecosystem

Whenever the assertion is disputed on a production network this triggers DVM request to be resolved by UMA voters. This might be impractical to fully simulate this in a testing environment, hence, developers can use mocked oracle contract to resolve requests as they had been returned by DVM.

Interacting with Optimistic Oracle requires having whitelisted price identifier and bonding currency. In production networks these are approved by UMA token holders as part of governance voting. When testing, it might be easier for developers to use their own set of UMA ecosystem contracts where they have full control over such whitelisting process. Follow the written tutorial below or check out the video tutorial on Youtube.

Deploying sandboxed Oracle environment

A set of sandboxed UMA ecosystem contracts can be deployed using forge script from .

After cloning the repository make sure you have the latest Foundry version by running foundryup command (see more installation details on ). From the root of the repository install dependencies with:

All script parameters are controlled through environment variables that should be exported before running the script:

• ETH_RPC_URL: URL of the RPC node to use for broadcasting deployment transactions on the desired test network.

• MNEMONIC: Mnemonic of the account to use for deployment (derived account with 0 index will be used by default).

• ETHERSCAN_API_KEY: API key for Etherscan, used for verifying deployed contracts.

Once all required environment variables are setup, deploy and verify the set of sandboxed UMA ecosystem contracts with:

At the top of the script output the addresses of the deployed contracts should be logged:

• Finder: Used to locate other UMA ecosystem contract addresses. Deployment script will have added new Store, AddressWhitelist, IdentifierWhitelist, MockOracleAncillary and OptimisticOracleV3 implementations.

• Store: Stores final fees of bonding currencies. The script will have set the final fee of default currency to half of provided minimum bond amount since Optimistic Oracle V3 calculates minimum bond twice the value of this final fee.

Resolving dispute requests

Whenever the assertion is disputed, Optimistic Oracle V3 calls requestPrice method on the Oracle that triggers DVM vote on mainnet. In the sandboxed environment this would resolve to MockOracleAncillary contract instead.

The disputed request is uniquely identified by its identifier, timestamp and ancillary data that should be referenced by the testing developer pushing resolved price to the mocked oracle. The MockOracleAncillary contract will emit PriceRequestAdded event with following parameters:

• address indexed requester: Address of the calling contract (Optimistic Oracle V3 in the sandboxed setup).

• bytes32 indexed identifier: Identifier referencing the rules on how the request should be resolved. By default Optimistic Oracle V3 uses ASSERT_TRUTH identifier unless the integrating contract provided other value.

• uint256 time

Note that production voting contract on mainnet emits this differently and above PriceRequestAdded is provided only as a convenience for developers when interacting with the MockOracleAncillary contract in their testing environment.

MockOracleAncillary contract provides two alternative methods for testing developers to resolve request:

• pushPrice(bytes32 identifier, uint256 time, bytes memory ancillaryData, int256 price) where request is referenced by its individual parameters.

• pushPriceByRequestId(bytes32 requestId, int256 price) where request is referenced by the hashed value of its identifying parameters.

While testing developer can pass any int256 price value, Optimistic Oracle V3 can only interpret value of 1e18 to represent truthful assertion. Any other value would settle assertion as being false. Also note that MockOracleAncillary contract will only accept the first pushed price to resolve a given request.

Example dispute flow

As an illustration to the section above this example walks through resolving disputed assertion with cast tool from Foundry. This also requires jq being installed for parsing returned values.

Just for the sake of simplicity set MINIMUM_BOND environment variable to 0 when running forge script command as discussed in the . This would allow to skip minting and approving assertion/dispute bonds. Take a note of deployed contracts log and export Optimistic Oracle V3 address to OOV3_ADDRESS and MockOracleAncillary address to MOCK_ORACLE_ADDRESS environment variables.

Also to keep this simple perform all steps from the same address:

Start with generating test assertion and grab the resulting assertionId emitted by Optimistic Oracle V3 (corresponds to topic index 1 in the AssertionMade event):

Dispute the above assertion and grab the resulting requestId emitted by MockOracleAncillary (corresponds to topic index 3 in the PriceRequestAdded event):

Now resolve the disputed assertion as truthful by pushing 1e18 as price to MockOracleAncillary contract:

This allows us to settle the assertion at Optimistic Oracle V3:

Finally, you can verify that Optimistic Oracle V3 has correctly settled the assertion (this should return true):

Further sandbox configuration

The deployment script documented in the covers most common use cases and should be sufficient to test example contracts from the . Though, when developing your own integrating contracts it might be required to further configure the sandboxed oracle environment.

Whitelisting of bonding currencies

In case the integrating contract requires handling assertion bonds in multiple currencies all of them should be approved at the AddressWhitelist contract. On production this should go through UMA governance while in the sandboxed environment the deployer owns this contract and can call addToWhitelist method directly. Assuming the address of AddressWhitelist contract is exported to ADDRESS_WHITELIST and required bonding currency is exported to BONDING_CURRENCY environment variables, this can be done by:

In order to test the scenario on how the integrating contracts would behave if UMA governance removed support for a particular bonding currency, you can test this by calling removeFromWhitelist method on the AddressWhitelist contract:

Note that Optimistic Oracle V3 is caching whitelisted bonding currencies. Hence, before testing impact on the integrating contracts somebody should sync the contract cache (anyone has authority to do this):

Changing the final fee

In case the UMA governance was to change the configured final fee for a particular bonding currency this would also change the minimum assertion bond required by Optimistic Oracle V3. In order to test such impact on integrating contracts in the testing environment, the deployer would need to call setFinalFee on the Store contract (exported as STORE_ADDRESS). E.g. to set final fee to 1000e18, you would call:

Again, before testing impact on integrating contracts someone would need to sync new final fee at the Optimistic Oracle V3:

Whitelisting of identifiers

If the integrating contract plans to make assertions with multiple identifiers, the developer would need to add them to IdentifierWhitelist contract (exported as IDENTIFIER_ADDRESS) in the sandboxed environment, e.g. adding CUSTOM_IDENTIFIER:

In order to test the scenario on how the integrating contracts would behave if UMA governance removed support for a particular identifier, you can test this by calling removeSupportedIdentifier method on the IdentifierWhitelist contract:

Note that Optimistic Oracle V3 is caching whitelisted identifiers. Hence, before testing impact on the integrating contracts somebody should sync the contract cache (anyone has authority to do this):

What is the ASSERT_TRUTH identifier?

oSnap uses the ASSERT_TRUTH identifier can be found here. ASSERT_TRUTH is intended to be used as a default price identifier for UMA's Optimistic Oracle V3 contract that allows asserters to make claims about the state of the world.

Price settlement can happen only in one of two ways:

• Return the 1 value if the claim is true.

• Return the 0 value if the claim is false or cannot be resolved.

Part 1: Snapshot Proposal Created

When a Snapshot proposal is created, a Discord ticket is created with a Tenderly simulation of the transaction payload. Here is an example:

The main objective of verifying the Snapshot proposal before voting is to ensure:

• The transaction payload can be executed

• Comparing the intent of the proposal against the transaction payload

• The transaction payload doesn't have any unintended consequences or malicious intent

In the Tenderly simulation, if the Status value is not Success, that is an indicator the transaction payload is unable to be executed and requires further review.

The input shows the transactions array that will be executed if the Snapshot proposal passes:

Verifying the transaction data

1. Go to .

2. Input the contract ABI into the ABI section

   1. Take the ‘to’ value from the transaction object and input it into etherscan (or the block explorer based on the chainID. For etherscan, you would go to }.

Here is what the example would look like:

The ‘Output’ for a Transfer should look as the below:

Verify the following:

• For any BigNumber values, go to and input BigNumber.from("{INPUT_VALUE}").toString(). For example, BigNumber.from("0x14adf4b7320334b9000000").toString() would be 25000000000000000000000000. To scale this value, go to the token contract address and check decimals. For the ACX token, the decimals are 18 so the scaled value is 25000000. You can use if the decimals are 18.

• Confirm that the above value is mentioned in the actual Snapshot proposal.

Part 2: oSnap Transactions Proposed

After a Snapshot proposal is completed, if the proposal is valid the transactions are proposed which creates another Discord ticket. is an example thread in the UMA Discord.

The first objective is to verify the oSnap rules against Snapshot Proposal. Click the Snapshot space URL, in the above example that is . Go through the list of proposals and confirm the explanation from the Discord message matches the Snapshot space.

Validators should do the following to verify the oSnap proposal:

• Check the Snapshot space referenced in the rules string.

• Check that the IPFS hash passed as the explanation lines up with an actual vote in that Snapshot space. They should be able to cross-reference the value with a link from a specific Snapshot proposal.

• Check the Snapshot proposal tied to the IPFS explanation value met the minimum voting period and quorum.

Compare Snapshot IPFS Transaction data against Proposed Transactions

1. Go to the Snapshot proposal and click the ‘View Details’ link in the Transactions container:

1. Copy the “transactions” array into . You should use Firefox or Brave so that backslashes “\” aren’t included in the array which will give you an error message when trying to parse:

3. In the Discord post, click the transaction:’

Then copy the ‘Transaction Hash’:

Go to and paste the ‘Transaction Hash’. Then click ‘Show’ to check the input data.

In the Discord Ticket, paste the screenshots of Tenderly and json formatter and also paste the transaction data into another thread message as below:

The following should be verified:

• ‘data’ from Tenderly matches the transaction data from Snapshot.

• ‘value’ from Tenderly matches the transaction data from Snapshot.

• ‘to’ from Tenderly matches the transaction data from Snapshot.

• Verify the explanation:

In this section, we'll talk about the , which you can find in the . This tutorial will show how event-based OO data requests can be used in a binary prediction market.

You will find out how this smart contract works and how to test it and deploy it. Refer to the contract for additional information on the event-based price requests.

The Event-Based Prediction Market

This smart contract lets you set up prediction markets that are based on an event-based price request.

The following are the evaluation criteria UMA considers when adding Optimistic Oracle support for a new network. UMA aims to support as many networks as possible to deliver the best experience for our integrating protocols and users. However, integrating a new network requires a significant investment. Therefore, the evaluation criteria were established to ensure that the benefits to UMA's integrating protocols and users outweigh the development, security, and operational costs of adding a new network.

Please note that these requirements are subject to change as the EVM (Ethereum Virtual Machine) and Layer 2 ecosystem continue to evolve. Meeting these requirements is the initial step in our evaluation process and does not guarantee support.

Non-Negotiable Criteria:

The below are a pre-requisite to any consideration:

Monitored

Risk Labs operates monitoring bots for the following networks and integrations for additional resiliency.

Unmonitored

The following networks are supported, but Risk Labs does not provide additional monitoring

Deprecated