Writing

Evaluating UMA's Long Short Pair Contracts for Upside on Base

· Blockchain · Engineering Notes, Smart Contracts, Web3

Drafted August 2024. Finished and published August 2026 as part of the migration away from WordPress.

In July I evaluated UMA’s Long Short Pair contracts as the issuance and settlement layer for Upside, a no-code KPI-token product we were exploring on Base. The product would let somebody define a measurable target, deposit collateral and issue tokens whose redemption value depended on the result.

The attraction was that UMA had already separated two problems that are easy to mix together: deciding the result and deciding what that result means financially. The Optimistic Oracle could resolve a value, while a financial product library could turn it into a payout.

By the end of August, the technical route was open. UMA had deployed the missing contracts to Base and Base Sepolia following our integration request. We did not proceed with the integration because the product direction moved away from the KPI-token design, not because the oracle or contracts failed the evaluation.

The contracts I evaluated

The main entry point was LongShortPairCreator. A call to createLongShortPair produces three new contract addresses, but only two contract types:

  1. A LongShortPair instance that holds the collateral and manages minting, redemption and settlement.
  2. A separate SyntheticToken instance used as the LONG token.
  3. Another SyntheticToken instance used as the SHORT token.

The creator calls the shared TokenFactory.createToken function twice, then deploys the LongShortPair. It gives the LSP permission to mint and burn both tokens, transfers ownership of both token contracts to the LSP, and emits all three addresses in CreatedLongShortPair.

The creator, token factory, financial product library, Finder and Optimistic Oracle are shared infrastructure. They are additional contracts in the overall system, but they are not redeployed for every market. Each LSP still needs a one-time, permissionless setLongShortPairParameters call on its library before payouts work, and the creator does not make that call.

Calling LongShortPair.create deposits collateralPerPair for every pair minted. The caller receives an equal number of LONG and SHORT tokens. Before expiry, matching LONG and SHORT tokens can be burned together to recover their collateral. After the oracle result has settled, settle can burn either side independently for its share.

The LongShortPair constructor also fixes the parts of the oracle request that matter later:

  • the expiration timestamp;
  • the supported price identifier;
  • the collateral token;
  • custom ancillary data describing the question;
  • the proposer reward;
  • the oracle liveness period;
  • the proposer bond;
  • the financial product library used for the payout.

The contract discovers UMA’s Optimistic Oracle V2 through the protocol’s Finder, rather than receiving a fixed oracle address for each pair.

Resolution and payout are separate

At expiry, once someone calls expire(), the LSP requests a price from the Optimistic Oracle. For this template the settled result is an int256 called expiryPrice. The LSP then passes that value to its financial product library, which returns a uint256 between 0 and 1e18:

expiryPrice = optimisticOracle.settleAndGetPrice(
    priceIdentifier,
    expirationTimestamp,
    customAncillaryData
);

expiryPercentLong = Math.min(
    financialProductLibrary.percentageLongCollateralAtExpiry(expiryPrice),
    1e18
);

expiryPercentLong determines the LONG side’s fraction of the collateral. The SHORT side receives the remainder.

The source implements those two steps in _getOraclePrice and getExpirationPrice.

That boundary made the design useful for more than a yes-or-no question. The oracle did not need to know whether the product used a binary payout, a linear range or another curve. It only needed to resolve the requested value.

Binary and linear markets

The first proof of concept was going to support two payout shapes.

LibraryLONG payout
BinaryOptionLongShortPairFinancialProductLibrary1e18 when the expiry price is at or above the strike, otherwise 0
LinearLongShortPairFinancialProductLibrary0 below the lower bound, 1e18 above the upper bound, and a proportional value between them

For a linear market, the value inside the bounds is:

(expiryPrice - lowerBound) / (upperBound - lowerBound)

Two charts of long-side payout against expiry price: a step at the strike for a binary market, and a ramp across a range for a linear market

The Optimistic Oracle supplies the expiry price. The selected library determines how that value divides the collateral between LONG and SHORT holders.

The base LongShortPairFinancialProductLibrary is an abstract contract defining the percentageLongCollateralAtExpiry interface. It is not itself a pass-through payout implementation.

Ancillary data was part of the product

The contract code could stay the same across several types of KPI. The category-specific work lived mainly in the ancillary data supplied with the oracle request.

A price-target market, for example, needs more than a token symbol and target value. The question must define the data source, quote currency, observation period, rounding and what happens when the source is unavailable or ambiguous. Those details determine whether a proposer and a disputer can independently reach the same answer.

The LSP passes its custom ancillary data to the oracle together with the identifier and timestamp. During construction it also checks the size after the oracle stamps the data with the requesting contract’s address. That prevents two otherwise identical questions from different LSPs being treated as the same request.

The first proof of concept was going to start with price targets, then add categories once their resolution language was precise enough.

Getting the contracts onto Base

The first practical problem was deployment. Ethereum had a LongShortPairCreator, but neither Base nor Base Sepolia had the creator and payout libraries needed to build against.

I raised this with Alex at UMA while confirming my reading of the contracts. We also confirmed that the application could supply its own frontend, so the contracts did not need to be added to projects.uma.xyz before we could use them.

UMA opened and merged the Base deployment pull request on 5 August. It added the token factory, LongShortPairCreator and seven financial product libraries to Base and Base Sepolia, including the binary and linear libraries I had been evaluating.

The pull request describes these as contract deployments without frontend or bot support. That qualification applies to the LSP product tooling. It does not mean Base received an isolated oracle with no dispute system behind it. Base already had UMA’s Finder, OptimisticOracleV2, whitelists and oracle bridge contracts. The new deployment added the LSP layer that uses that existing infrastructure.

Where the evaluation ended

The missing contracts began as an integration blocker, but they were not the reason the integration stopped. UMA resolved that blocker. By then, the product work had moved away from the KPI-token design, so I did not build the planned proof of concept against the new Base deployment.

The evaluation still produced a useful technical model:

  • token issuance and oracle resolution can remain separate;
  • one resolved value can support several payout functions;
  • ancillary data is part of the market’s specification, not an incidental string;
  • liveness, rewards and bonds belong in the product design as well as the contract configuration;
  • a chain deployment needs the creator, token factory and selected payout libraries in addition to the oracle itself.

The conclusion at the end of August is narrower than “use UMA” or “build it ourselves”. UMA’s LSP contracts could express the binary and linear KPI markets we were considering, and the required contracts were now available on Base. The product question changed before that technical path became an integration.

← All posts