@gnosis.pm/pm-contracts

<!DOCTYPE html>   <html class="no-js" lang="en" >  <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Developer Guide — Gnosis Prediction Market Contracts 2.0.0-alpha.2 documentation</title> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="index" title="Index" href="genindex.html"/> <link rel="search" title="Search" href="search.html"/> <link rel="top" title="Gnosis Prediction Market Contracts 2.0.0-alpha.2 documentation" href="index.html"/> <link rel="next" title="Changes from Version 1.x" href="changes-from-v1.html"/> <link rel="prev" title="Gnosis Prediction Market Contracts" href="index.html"/> <script src="_static/js/modernizr.min.js"></script> </head> <body class="wy-body-for-nav" role="document"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="index.html" class="icon icon-home"> Gnosis Prediction Market Contracts </a> <div class="version"> 2.0 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> Contents: <ul class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="#">Developer Guide</a><ul> <li class="toctree-l2"><a class="reference internal" href="#prerequisites">Prerequisites</a></li> <li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a><ul> <li class="toctree-l3"><a class="reference internal" href="#via-npm">Via NPM</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#preparing-a-condition">Preparing a Condition</a><ul> <li class="toctree-l3"><a class="reference internal" href="#a-categorical-example">A Categorical Example</a></li> <li class="toctree-l3"><a class="reference internal" href="#a-scalar-example">A Scalar Example</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#outcome-collections">Outcome Collections</a><ul> <li class="toctree-l3"><a class="reference internal" href="#categorical-example-featuring-alice-bob-and-carol">Categorical Example Featuring Alice, Bob, and Carol</a></li> <li class="toctree-l3"><a class="reference internal" href="#index-set-representation-and-identifier-derivation">Index Set Representation and Identifier Derivation</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#defining-positions">Defining Positions</a></li> <li class="toctree-l2"><a class="reference internal" href="#splitting-and-merging-positions">Splitting and Merging Positions</a><ul> <li class="toctree-l3"><a class="reference internal" href="#basic-splits">Basic Splits</a></li> <li class="toctree-l3"><a class="reference internal" href="#splits-to-deeper-positions">Splits to Deeper Positions</a></li> <li class="toctree-l3"><a class="reference internal" href="#splits-on-partial-partitions">Splits on Partial Partitions</a></li> <li class="toctree-l3"><a class="reference internal" href="#merging-positions">Merging Positions</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#querying-and-transferring-stake">Querying and Transferring Stake</a></li> <li class="toctree-l2"><a class="reference internal" href="#redeeming-positions">Redeeming Positions</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="changes-from-v1.html">Changes from Version 1.x</a></li> <li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing</a></li> <li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> <a href="index.html">Gnosis Prediction Market Contracts</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html">Docs</a> »</li> <li>Developer Guide</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/developer-guide.rst.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="developer-guide"> <h1>Developer Guide<a class="headerlink" href="#developer-guide" title="Permalink to this headline">¶</a></h1> <div class="admonition warning"> Warning This document refers to a version of the framework which is under development. Some things may change. You may also be interested in <a class="reference external" href="https://gnosis-pm-contracts.readthedocs.io/en/v1/">v1</a> of this framework. </div> <div class="section" id="prerequisites"> <h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2> Usage of this smart contract system requires some proficiency in <a class="reference external" href="https://solidity.readthedocs.io">Solidity</a>. Additionally, this guide will assume a <a class="reference external" href="https://truffleframework.com">Truffle</a> based setup. Client-side code samples will be written in JavaScript assuming the presence of a <a class="reference external" href="https://web3js.readthedocs.io/en/1.0/">web3.js</a> instance and various <a class="reference external" href="https://github.com/trufflesuite/truffle/tree/next/packages/truffle-contract#truffle-contract">TruffleContract</a> wrappers. The current state of this smart contract system may be found on <a class="reference external" href="https://github.com/gnosis/pm-contracts">Github</a>. </div> <div class="section" id="installation"> <h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2> <div class="section" id="via-npm"> <h3>Via NPM<a class="headerlink" href="#via-npm" title="Permalink to this headline">¶</a></h3> This developmental framework may be installed from Github through NPM by running the following: <div class="highlight-default notranslate"><div class="highlight"><pre>npm i gnosis/pm-contracts </pre></div> </div> </div> </div> <div class="section" id="preparing-a-condition"> <h2>Preparing a Condition<a class="headerlink" href="#preparing-a-condition" title="Permalink to this headline">¶</a></h2> Before predictive assets can exist in the system, a condition must be prepared. A condition is a question to be answered in the future by a specific oracle in a particular manner. The following function may be used to prepare a condition: <dl class="function"> <dt id="prepareCondition(address,bytes32,uint)"> function <code class="descname">prepareCondition</code>(address oracle, bytes32 questionId, uint outcomeSlotCount)<a class="headerlink" href="#prepareCondition(address,bytes32,uint)" title="Permalink to this definition">¶</a> external <a class="headerlink" href="#prepareCondition(address,bytes32,uint)" title="Permalink to this definition">¶</a></dt> <dd>This function prepares a condition by initializing a payout vector associated with the condition. <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> <li>oracle – The account assigned to report the result for the prepared condition.</li> <li>questionId – An identifier for the question to be answered by the oracle.</li> <li>outcomeSlotCount – The number of outcome slots which should be used for this condition. Must not exceed 256.</li> </ul> </td> </tr> </tbody> </table> </dd></dl> <div class="admonition note"> Note It is up to the consumer of the contract to interpret the question ID correctly. For example, a client may interpret the question ID as an IPFS hash which can be used to retrieve a document specifying the question more fully. The meaning of the question ID is left up to clients. </div> If the function succeeds, the following event will be emitted, signifying the preparation of a condition: <dl class="event"> <dt id="ConditionPreparation(bytes32,address,bytes32,uint)"> event <code class="descname">ConditionPreparation</code>(bytes32 indexed conditionId, address indexed oracle, bytes32 indexed questionId, uint outcomeSlotCount)<a class="headerlink" href="#ConditionPreparation(bytes32,address,bytes32,uint)" title="Permalink to this definition">¶</a> <a class="headerlink" href="#ConditionPreparation(bytes32,address,bytes32,uint)" title="Permalink to this definition">¶</a></dt> <dd>Emitted upon the successful preparation of a condition. <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> <li>conditionId – The condition’s ID. This ID may be derived from the other three parameters via <code class="docutils literal notranslate">keccak256(abi.encodePacked(oracle, questionId, outcomeSlotCount))</code>.</li> <li>oracle – The account assigned to report the result for the prepared condition.</li> <li>questionId – An identifier for the question to be answered by the oracle.</li> <li>outcomeSlotCount – The number of outcome slots which should be used for this condition. Must not exceed 256.</li> </ul> </td> </tr> </tbody> </table> </dd></dl> <div class="admonition note"> Note The condition ID is different from the question ID, and their distinction is important. </div> The successful preparation of a condition also initializes the following state variable: <dl class="statevar"> <dt id="payoutNumerators"> mapping (bytes32 => uint[]) public <code class="descname">payoutNumerators</code><a class="headerlink" href="#payoutNumerators" title="Permalink to this definition">¶</a></dt> <dd>Mapping key is an condition ID. Value represents numerators of the payout vector associated with the condition. This array is initialized with a length equal to the outcome slot count. </dd></dl> To determine if, given a condition’s ID, a condition has been prepared, or to find out a condition’s outcome slot count, use the following accessor: <dl class="function"> <dt id="getOutcomeSlotCount(bytes32)"> function <code class="descname">getOutcomeSlotCount</code>(bytes32 conditionId)<a class="headerlink" href="#getOutcomeSlotCount(bytes32)" title="Permalink to this definition">¶</a> external view returns (uint) <a class="headerlink" href="#getOutcomeSlotCount(bytes32)" title="Permalink to this definition">¶</a></dt> <dd>Gets the outcome slot count of a condition. <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li>conditionId – ID of the condition.</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Return:</th><td class="field-body">Number of outcome slots associated with a condition, or zero if condition has not been prepared yet. </td> </tr> </tbody> </table> </dd></dl> The resultant payout vector of a condition contains a predetermined number of outcome slots. The entries of this vector are reported by the oracle, and their values sum up to one. This payout vector may be interpreted as the oracle’s answer to the question posed in the condition. <div class="section" id="a-categorical-example"> <h3>A Categorical Example<a class="headerlink" href="#a-categorical-example" title="Permalink to this headline">¶</a></h3> Let’s consider a question where only one out of multiple choices may be chosen: <blockquote> <div>Who out of the following will be chosen? <ul class="simple"> <li>Alice</li> <li>Bob</li> <li>Carol</li> </ul> </div></blockquote> Through some commonly agreed upon mechanism, the detailed description for this question becomes strongly associated with a 32 byte question ID: <code class="docutils literal notranslate">0xabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc1234</code> Let’s also suppose we trust the oracle with address <code class="docutils literal notranslate">0x1337aBcdef1337abCdEf1337ABcDeF1337AbcDeF</code> to deliver the answer for this question. To prepare this condition, the following code gets run: <div class="highlight-js notranslate"><div class="highlight"><pre>await predictionMarketSystem.prepareCondition( '0x1337aBcdef1337abCdEf1337ABcDeF1337AbcDeF', '0xabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc1234', 3 ) </pre></div> </div> The condition ID may also be determined from the parameters via: <div class="highlight-js notranslate"><div class="highlight"><pre>web3.utils.soliditySha3({ t: 'address', v: '0x1337aBcdef1337abCdEf1337ABcDeF1337AbcDeF' }, { t: 'bytes32', v: '0xabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc1234' }, { t: 'uint', v: 3 }) </pre></div> </div> This yields a condition ID of <code class="docutils literal notranslate">0x67eb23e8932765c1d7a094838c928476df8c50d1d3898f278ef1fb2a62afab63</code>. Later, if the oracle <code class="docutils literal notranslate">0x1337aBcdef1337abCdEf1337ABcDeF1337AbcDeF</code> makes a report that the payout vector for the condition is <code class="docutils literal notranslate">[0, 1, 0]</code>, the oracle essentially states that Bob was chosen, as the outcome slot associated with Bob would receive all of the payout. </div> <div class="section" id="a-scalar-example"> <h3>A Scalar Example<a class="headerlink" href="#a-scalar-example" title="Permalink to this headline">¶</a></h3> Let us now consider a question where the answer may lie in a range: <blockquote> <div>What will the score be? [0, 1000]</div></blockquote> Let’s say the question ID for this question is <code class="docutils literal notranslate">0x777def777def777def777def777def777def777def777def777def777def7890</code>, and that we trust the oracle <code class="docutils literal notranslate">0xCafEBAbECAFEbAbEcaFEbabECAfebAbEcAFEBaBe</code> to deliver the results for this question. To prepare this condition, the following code gets run: <div class="highlight-js notranslate"><div class="highlight"><pre>await predictionMarketSystem.prepareCondition( '0xCafEBAbECAFEbAbEcaFEbabECAfebAbEcAFEBaBe', '0x777def777def777def777def777def777def777def777def777def777def7890', 2 ) </pre></div> </div> The condition ID for this condition can be calculated as <code class="docutils literal notranslate">0x3bdb7de3d0860745c0cac9c1dcc8e0d9cb7d33e6a899c2c298343ccedf1d66cf</code>. In this case, the condition was created with two slots: one which represents the low end of the range (0) and another which represents the high end (1000). The slots’ reported payout values should indicate how close the answer was to these endpoints. For example, if the oracle <code class="docutils literal notranslate">0xCafEBAbECAFEbAbEcaFEbabECAfebAbEcAFEBaBe</code> makes a report that the payout vector is <code class="docutils literal notranslate">[9/10, 1/10]</code>, then the oracle essentially states that the score was 100, as the slot corresponding to the low end is worth nine times what the slot corresponding with the high end is worth, meaning the score should be nine times closer to 0 than it is close to 1000. Likewise, if the payout vector is reported to be <code class="docutils literal notranslate">[0, 1]</code>, then the oracle is saying that the score was at least 1000. </div> </div> <div class="section" id="outcome-collections"> <h2>Outcome Collections<a class="headerlink" href="#outcome-collections" title="Permalink to this headline">¶</a></h2> The main concept for understanding the mechanics of this system is that of a position. We will build to this concept from conditions and outcome slots, and then demonstrate the use of this concept. However, before we can talk about positions, we first have to talk about outcome collections, which may be defined like so: <blockquote> <div>A nonempty proper subset of a condition’s outcome slots which represents the sum total of all the contained slots’ payout values.</div></blockquote> <div class="section" id="categorical-example-featuring-alice-bob-and-carol"> <h3>Categorical Example Featuring Alice, Bob, and Carol<a class="headerlink" href="#categorical-example-featuring-alice-bob-and-carol" title="Permalink to this headline">¶</a></h3> We’ll denote the outcome slots for Alice, Bob, and Carol as <code class="docutils literal notranslate">A</code>, <code class="docutils literal notranslate">B</code>, and <code class="docutils literal notranslate">C</code> respectively. A valid outcome collection may be <code class="docutils literal notranslate">(A|B)</code>. In this example, this outcome collection represents the eventuality in which either Alice or Bob is chosen. Note that for a categorical condition, the payout vector which the oracle reports will eventually contain a one in exactly one of the three slots, so the sum of the values in Alice’s and Bob’s slots is one precisely when either Alice or Bob is chosen, and zero otherwise. <code class="docutils literal notranslate">(C)</code> by itself is also a valid outcome collection, and this simply represents the case where Carol is chosen. <code class="docutils literal notranslate">()</code> is an invalid outcome collection, as it is empty. Empty outcome collections do not make sense, as they would essentially represent no eventuality and have no value no matter what happens. Conversely, <code class="docutils literal notranslate">(A|B|C)</code> is also an invalid outcome collection, as it is not a proper subset. Outcome collections consisting of all the outcome slots for a condition also do not make sense, as they would simply represent any eventuality, and should be equivalent to whatever was used to collateralize these outcome collections. Finally, outcome slots from different conditions (e.g. <code class="docutils literal notranslate">(A|X)</code>) cannot be composed in a single outcome collection. </div> <div class="section" id="index-set-representation-and-identifier-derivation"> <h3>Index Set Representation and Identifier Derivation<a class="headerlink" href="#index-set-representation-and-identifier-derivation" title="Permalink to this headline">¶</a></h3> A outcome collection may be represented by an a condition and an index set. This is a 256 bit array which denotes which outcome slots are present in a outcome collection. For example, the value <code class="docutils literal notranslate">3 == 0b011</code> corresponds to the outcome collection <code class="docutils literal notranslate">(A|B)</code>, whereas the value <code class="docutils literal notranslate">4 == 0b100</code> corresponds to <code class="docutils literal notranslate">(C)</code>. Note that the indices start at the lowest bit in a <code class="docutils literal notranslate">uint</code>. A outcome collection may be identified with a 32 byte value called a collection identifier. In order to calculate the collection ID for <code class="docutils literal notranslate">(A|B)</code>, simply hash the condition ID and the index set: <div class="highlight-js notranslate"><div class="highlight"><pre>web3.utils.soliditySha3({ // See section "A Categorical Example" for derivation of this condition ID t: 'bytes32', v: '0x67eb23e8932765c1d7a094838c928476df8c50d1d3898f278ef1fb2a62afab63' }, { t: 'uint', v: 0b011 // Binary Number literals supported in newer versions of JavaScript }) </pre></div> </div> This results in a collection ID of <code class="docutils literal notranslate">0x52ff54f0f5616e34a2d4f56fb68ab4cc636bf0d92111de74d1ec99040a8da118</code>. We may also combine collection IDs for outcome collections for different conditions by adding their values modulo 2^256 (equivalently, by adding their values and then taking the lowest 256 bits). To illustrate, let’s denote the slots for range ends 0 and 1000 from our scalar condition example as <code class="docutils literal notranslate">LO</code> and <code class="docutils literal notranslate">HI</code>. We can find the collection ID for <code class="docutils literal notranslate">(LO)</code> to be <code class="docutils literal notranslate">0xd79c1d3f71f6c9d998353ba2a848e596f0c6c1a9f6fa633f2c9ec65aaa097cdc</code>. The combined collection ID for <code class="docutils literal notranslate">(A|B)&(LO)</code> can be calculated via: <div class="highlight-js notranslate"><div class="highlight"><pre>'0x' + BigInt.asUintN(256, 0x52ff54f0f5616e34a2d4f56fb68ab4cc636bf0d92111de74d1ec99040a8da118n + 0xd79c1d3f71f6c9d998353ba2a848e596f0c6c1a9f6fa633f2c9ec65aaa097cdcn ).toString(16) </pre></div> </div> <div class="admonition note"> Note <a class="reference external" href="https://tc39.github.io/proposal-bigint/">BigInt</a> is used here for the calculation, though <a class="reference external" href="https://github.com/indutny/bn.js/">BN.js</a> or <a class="reference external" href="https://github.com/MikeMcl/bignumber.js/">BigNumber.js</a> should both also suffice. </div> This calculation yields the value <code class="docutils literal notranslate">0x2a9b72306758380e3b0a31125ed39a635432b283180c41b3fe8b5f5eb4971df4</code>. </div> </div> <div class="section" id="defining-positions"> <h2>Defining Positions<a class="headerlink" href="#defining-positions" title="Permalink to this headline">¶</a></h2> In order to define a position, we first need to designate a collateral token. This token must be an <a class="reference external" href="https://theethereum.wiki/w/index.php/ERC20_Token_Standard">ERC20</a> token which exists on the same chain as the PredictionMarketSystem instance. Then we need at least one condition with a outcome collection, though a position may refer to multiple conditions each with an associated outcome collection. Positions become valuable precisely when all of its constituent outcome collections are valuable. More explicitly, the value of a position is a product of the values of those outcome collections composing the position. With these ingredients, position identifiers can also be calculated by hashing the address of the collateral token and the combined collection ID of all the outcome collections in the position. We say positions are deeper if they contain more conditions and outcome collections, and shallower if they contain less. As an example, let’s suppose that there is an ERC20 token called DollaCoin which exists at the address <code class="docutils literal notranslate">0xD011ad011ad011AD011ad011Ad011Ad011Ad011A</code>, and it is used as collateral for some positions. We will denote this token with <code class="docutils literal notranslate">$</code>. We may calculate the position ID for the position <code class="docutils literal notranslate">$:(A|B)</code> via: <div class="highlight-js notranslate"><div class="highlight"><pre>web3.utils.soliditySha3({ t: 'address', v: '0xD011ad011ad011AD011ad011Ad011Ad011Ad011A' }, { t: 'bytes32', v: '0x52ff54f0f5616e34a2d4f56fb68ab4cc636bf0d92111de74d1ec99040a8da118' }) </pre></div> </div> The ID for <code class="docutils literal notranslate">$:(A|B)</code> turns out to be <code class="docutils literal notranslate">0x6147e75d1048cea497aeee64d1a4777e286764ded497e545e88efc165c9fc4f0</code>. Similarly, the ID for <code class="docutils literal notranslate">$:(LO)</code> can be found to be <code class="docutils literal notranslate">0xfdad82d898904026ae6c01a5800c0a8ee9ada7e7862f9bb6428b6f81e06f53bb</code>, and <code class="docutils literal notranslate">$:(A|B)&(LO)</code> has an ID of <code class="docutils literal notranslate">0xcc77e750b61d29e158aa3193faa3673b2686ba9f6a16f51b5cdbea2a4f694be0</code>. All the positions backed by DollaCoin which depend on the example categorical condition and the example scalar condition form a DAG (directed acyclic graph): <div class="figure align-center" id="id1"> <img alt="DAG of every position which can be made from DollaCoin and the two example conditions, where the nodes are positions, edges are colored by condition, and directionality is implied with vertical spacing." src="_images/all-positions-from-two-conditions.png" /> Graph of all positions backed by <code class="docutils literal notranslate">$</code> which are contingent on either or both of the example conditions. </div> </div> <div class="section" id="splitting-and-merging-positions"> <h2>Splitting and Merging Positions<a class="headerlink" href="#splitting-and-merging-positions" title="Permalink to this headline">¶</a></h2> Once conditions have been prepared, stake in positions contingent on these conditions may be obtained. Furthermore, this stake must be backed by collateral held by the system. In order to ensure this is the case, stake in shallow positions may only be created directly by sending collateral to the system for the system to hold, and stake in deeper positions may only be created by destroying stake in shallower positions. Any of these is referred to as splitting a position, and is done through the following function: <dl class="function"> <dt id="splitPosition(IERC20,bytes32,bytes32,uint[],uint)"> function <code class="descname">splitPosition</code>(IERC20 collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] partition, uint amount)<a class="headerlink" href="#splitPosition(IERC20,bytes32,bytes32,uint[],uint)" title="Permalink to this definition">¶</a> external <a class="headerlink" href="#splitPosition(IERC20,bytes32,bytes32,uint[],uint)" title="Permalink to this definition">¶</a></dt> <dd>This function splits a position. If splitting from the collateral, this contract will attempt to transfer <cite>amount</cite> collateral from the message sender to itself. Otherwise, this contract will burn <cite>amount</cite> stake held by the message sender in the position being split. Regardless, if successful, <cite>amount</cite> stake will be minted in the split target positions. If any of the transfers, mints, or burns fail, the transaction will revert. The transaction will also revert if the given partition is trivial, invalid, or refers to more slots than the condition is prepared with. <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> <li>collateralToken – The address of the positions’ backing collateral token.</li> <li>parentCollectionId – The ID of the outcome collections common to the position being split and the split target positions. May be null, in which only the collateral is shared.</li> <li>conditionId – The ID of the condition to split on.</li> <li>partition – An array of disjoint index sets representing a nontrivial partition of the outcome slots of the given condition.</li> <li>amount – The amount of collateral or stake to split.</li> </ul> </td> </tr> </tbody> </table> </dd></dl> If this transaction does not revert, the following event will be emitted: <dl class="event"> <dt id="PositionSplit(address,IERC20,bytes32,bytes32,uint[],uint)"> event <code class="descname">PositionSplit</code>(address indexed stakeholder, IERC20 collateralToken, bytes32 indexed parentCollectionId, bytes32 indexed conditionId, uint[] partition, uint amount)<a class="headerlink" href="#PositionSplit(address,IERC20,bytes32,bytes32,uint[],uint)" title="Permalink to this definition">¶</a> <a class="headerlink" href="#PositionSplit(address,IERC20,bytes32,bytes32,uint[],uint)" title="Permalink to this definition">¶</a></dt> <dd>Emitted when a position is successfully split. </dd></dl> To decipher this function, let’s consider what would be considered a valid split, and what would be invalid: <div class="figure align-center" id="id2"> <img alt="Various valid and invalid splits of positions." src="_images/valid-vs-invalid-splits.png" /> Details for some of these scenarios will follow </div> <div class="section" id="basic-splits"> <h3>Basic Splits<a class="headerlink" href="#basic-splits" title="Permalink to this headline">¶</a></h3> Collateral <code class="docutils literal notranslate">$</code> can be split into outcome tokens in positions <code class="docutils literal notranslate">$:(A)</code>, <code class="docutils literal notranslate">$:(B)</code>, and <code class="docutils literal notranslate">$:(C)</code>. To do so, use the following code: <div class="highlight-js notranslate"><div class="highlight"><pre>const amount = 1e18 // could be any amount // user must allow predictionMarketSystem to // spend amount of DollaCoin, e.g. through // await dollaCoin.approve(predictionMarketSystem.address, amount) await predictionMarketSystem.splitPosition( // This is just DollaCoin's address '0xD011ad011ad011AD011ad011Ad011Ad011Ad011A', // For splitting from collateral, pass bytes32(0) '0x00', // "Choice" condition ID: // see A Categorical Example for derivation '0x67eb23e8932765c1d7a094838c928476df8c50d1d3898f278ef1fb2a62afab63', // Each element of this partition is an index set: // see Outcome Collections for explanation [0b001, 0b010, 0b100], // Amount of collateral token to submit for holding // in exchange for minting the same amount of // outcome token in each of the target positions amount, ) </pre></div> </div> The effect of this transaction is to transfer <code class="docutils literal notranslate">amount</code> DollaCoin from the message sender to the <code class="docutils literal notranslate">predictionMarketSystem</code> to hold, and to mint <code class="docutils literal notranslate">amount</code> of outcome token for the following positions: <table border="1" class="docutils"> <colgroup> <col width="11%" /> <col width="89%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Symbol</th> <th class="head">Position ID</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><code class="docutils literal notranslate">$:(A)</code></td> <td><code class="docutils literal notranslate">0x8c12fa3bb72c9c455acd4d6034989ec0ce9188afd7c89c8c42d064ed7fe5a9d8</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">$:(B)</code></td> <td><code class="docutils literal notranslate">0x21aec03d8dfd8b5f0a2750718fe491e439f3625816e383b66a05cabd56624b4c</code></td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">$:(C)</code></td> <td><code class="docutils literal notranslate">0x8085f7c500098412ff2fc701a74174527e7b39a2b923cd0bca6ad2d5f7fa348d</code></td> </tr> </tbody> </table> <div class="admonition note"> Note The previous example, where collateral was split into shallow positions containing collections with one slot each, is similar to <code class="docutils literal notranslate">Event.buyAllOutcomes</code> from v1. </div> The set of <code class="docutils literal notranslate">(A)</code>, <code class="docutils literal notranslate">(B)</code>, and <code class="docutils literal notranslate">(C)</code> is not the only nontrivial partition of outcome slots for the example categorical condition. For example, the set <code class="docutils literal notranslate">(B)</code> (with index set <code class="docutils literal notranslate">0b010</code>) and <code class="docutils literal notranslate">(A|C)</code> (with index set <code class="docutils literal notranslate">0b101</code>) also partitions these outcome slots, and consequently, splitting from <code class="docutils literal notranslate">$</code> to <code class="docutils literal notranslate">$:(B)</code> and <code class="docutils literal notranslate">$:(A|C)</code> is also valid and can be done with the following code: <div class="highlight-js notranslate"><div class="highlight"><pre>await predictionMarketSystem.splitPosition( '0xD011ad011ad011AD011ad011Ad011Ad011Ad011A', '0x00', '0x67eb23e8932765c1d7a094838c928476df8c50d1d3898f278ef1fb2a62afab63', // This partition differs from the previous example [0b010, 0b101], amount, ) </pre></div> </div> This transaction also transfers <code class="docutils literal notranslate">amount</code> DollaCoin from the message sender to the <code class="docutils literal notranslate">predictionMarketSystem</code> to hold, but it mints <code class="docutils literal notranslate">amount</code> of outcome token for the following positions instead: <table border="1" class="docutils"> <colgroup> <col width="14%" /> <col width="86%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Symbol</th> <th class="head">Position ID</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><code class="docutils literal notranslate">$:(B)</code></td> <td><code class="docutils literal notranslate">0x21aec03d8dfd8b5f0a2750718fe491e439f3625816e383b66a05cabd56624b4c</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">$:(A|C)</code></td> <td><code class="docutils literal notranslate">0xb33b3d0035913315b76e85842f682920f78b32c43c7175768c4c67e3f31e6413</code></td> </tr> </tbody> </table> <div class="admonition warning"> Warning If non-disjoint index sets are supplied to <code class="docutils literal notranslate">splitPosition</code>, the transaction will revert. Partitions must be valid partitions. For example, you can’t split <code class="docutils literal notranslate">$</code> to <code class="docutils literal notranslate">$:(A|B)</code> and <code class="docutils literal notranslate">$:(B|C)</code> because <code class="docutils literal notranslate">(A|B)</code> (<code class="docutils literal notranslate">0b011</code>) and <code class="docutils literal notranslate">(B|C)</code> (<code class="docutils literal notranslate">0b110</code>) share outcome slot <code class="docutils literal notranslate">B</code> (<code class="docutils literal notranslate">0b010</code>). </div> </div> <div class="section" id="splits-to-deeper-positions"> <h3>Splits to Deeper Positions<a class="headerlink" href="#splits-to-deeper-positions" title="Permalink to this headline">¶</a></h3> It’s also possible to split from a position, burning outcome tokens in that position in order to acquire outcome tokens in deeper positions. For example, you can split <code class="docutils literal notranslate">$:(A|B)</code> to target <code class="docutils literal notranslate">$:(A|B)&(LO)</code> and <code class="docutils literal notranslate">$:(A|B)&(HI)</code>: <div class="highlight-js notranslate"><div class="highlight"><pre>await predictionMarketSystem.splitPosition( // Note that we're still supplying the same collateral token // even though we're going two levels deep. '0xD011ad011ad011AD011ad011Ad011Ad011Ad011A', // Here, instead of just supplying 32 zero bytes, we supply // the collection ID for (A|B). // This is NOT the position ID for $:(A|B)! '0x52ff54f0f5616e34a2d4f56fb68ab4cc636bf0d92111de74d1ec99040a8da118', // This is the condition ID for the example scalar condition '0x3bdb7de3d0860745c0cac9c1dcc8e0d9cb7d33e6a899c2c298343ccedf1d66cf', // This is the only partition that makes sense // for conditions with only two outcome slots [0b01, 0b10], amount, ) </pre></div> </div> This transaction burns <code class="docutils literal notranslate">amount</code> of outcome token in position <code class="docutils literal notranslate">$:(A|B)</code> (position ID <code class="docutils literal notranslate">0x6147e75d1048cea497aeee64d1a4777e286764ded497e545e88efc165c9fc4f0</code>) in order to mint <code class="docutils literal notranslate">amount</code> of outcome token in the following positions: <table border="1" class="docutils"> <colgroup> <col width="19%" /> <col width="81%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Symbol</th> <th class="head">Position ID</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><code class="docutils literal notranslate">$:(A|B)&(LO)</code></td> <td><code class="docutils literal notranslate">0xcc77e750b61d29e158aa3193faa3673b2686ba9f6a16f51b5cdbea2a4f694be0</code></td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">$:(A|B)&(HI)</code></td> <td><code class="docutils literal notranslate">0xbacf3ddf0474d567cd254ea0674fe52ab20a3e2ebca00ec71a846f3c48c5de9d</code></td> </tr> </tbody> </table> </div> <div class="section" id="splits-on-partial-partitions"> <h3>Splits on Partial Partitions<a class="headerlink" href="#splits-on-partial-partitions" title="Permalink to this headline">¶</a></h3> Supplying a partition which does not cover the set of all outcome slots for a condition, but instead some outcome collection, is also possible. For example, it is possible to split <code class="docutils literal notranslate">$:(B|C)</code> (position ID <code class="docutils literal notranslate">0x5d06cd85e2ff915efab0e7881432b1c93b3e543c5538d952591197b3893f5ce3</code>) to <code class="docutils literal notranslate">$:(B)</code> and <code class="docutils literal notranslate">$:(C)</code>: <div class="highlight-js notranslate"><div class="highlight"><pre>await predictionMarketSystem.splitPosition( '0xD011ad011ad011AD011ad011Ad011Ad011Ad011A', // Note that we also supply zeroes here, as the only aspect shared // between $:(B|C), $:(B) and $:(C) is the collateral token '0x00', '0x67eb23e8932765c1d7a094838c928476df8c50d1d3898f278ef1fb2a62afab63', // This partition does not cover the first outcome slot [0b010, 0b100], amount, ) </pre></div> </div> </div> <div class="section" id="merging-positions"> <h3>Merging Positions<a class="headerlink" href="#merging-positions" title="Permalink to this headline">¶</a></h3> Merging positions does