diff --git a/docs/appendix/states/failure.adoc b/docs/appendix/states/failure.adoc index d904c282c..f96c80e86 100644 --- a/docs/appendix/states/failure.adoc +++ b/docs/appendix/states/failure.adoc @@ -84,7 +84,7 @@ fraud-related state transitions in a single document. * *access controls* ** anyone * *reads* -** ORACLE +** PRICE_FEED * *writes* * *from* ** `ACTIVE` @@ -195,7 +195,7 @@ fraud-related state transitions in a single document. * *access controls* ** anyone * *reads* -** ORACLE +** PRICE_FEED * *writes* ** `uint256 courtesyCallInitiated` *** timestamp when the call was initiated @@ -232,7 +232,7 @@ fraud-related state transitions in a single document. ** `uint256 fundedAt` *** to check if the deposit is expiring ** `bool getCollateralizationPercentage() < TBTCConstants.getUndercollateralizedPercent()` -*** Check the oracle to see if collateral is sufficient +*** Check the price feed to see if collateral is sufficient * *from* ** `COURTESY_CALL` * *to* diff --git a/docs/appendix/states/redemption.adoc b/docs/appendix/states/redemption.adoc index 418160539..551b7f00d 100644 --- a/docs/appendix/states/redemption.adoc +++ b/docs/appendix/states/redemption.adoc @@ -111,8 +111,8 @@ funder bond payment. ** `bytes _bitcoinHeaders` * *reads* ** `bytes requesterPKH` -** `uint256 oracleDifficultyReq` -*** from oracle contract +** `uint256 difficultyReq` +*** from difficulty relay contract ** `uint256 depositSize` ** `uint256 initialWithdrawalFee` * *writes* diff --git a/docs/bonding/index.adoc b/docs/bonding/index.adoc index a9407fcd4..0c3e43fbb 100644 --- a/docs/bonding/index.adoc +++ b/docs/bonding/index.adoc @@ -91,6 +91,7 @@ up their collateral. // TODO insert a little historical analysis for a decent starting number + === BTC price drop relative to ETH Since <> are denominated per BTC in custody (with @@ -118,7 +119,7 @@ signer redeems the Deposit by paying 1 TBTC, reclaiming 1 BTC and unlocking the 75 ETH which was locked by all Signers. All significantly overcollateralized Signers now have liquid ETH which they can use to back another deposit to mint new TBTC. -== A resilient price oracle +== A resilient price feed Unlike popular synthetic stablecoin schemes, the tBTC system design makes no effort to stabilize the value of TBTC relative to BTC -- TBTC will be priced by @@ -130,7 +131,7 @@ between the signing bond collateral and BTC. In concrete terms, that means the price of ETH to BTC. Due to only needing prices for a single pair of assets, tBTC will initially use a simple -<>. +<>. == Undercollateralization diff --git a/docs/index.adoc b/docs/index.adoc index f5e42c239..01b42b80a 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -251,7 +251,7 @@ include::deposits/index.adoc[leveloffset=+2] include::bonding/index.adoc[leveloffset=+2] -include::price-oracle/index.adoc[leveloffset=+2] +include::price-feed/index.adoc[leveloffset=+2] include::minting/index.adoc[leveloffset=+2] diff --git a/docs/price-oracle/index.adoc b/docs/price-feed/index.adoc similarity index 67% rename from docs/price-oracle/index.adoc rename to docs/price-feed/index.adoc index 2b15c6326..9f1eeda66 100644 --- a/docs/price-oracle/index.adoc +++ b/docs/price-feed/index.adoc @@ -1,12 +1,12 @@ [env.theorem] :toc: macro -[#price-oracle] -= Price Oracle +[#price-feed] += Price Feed ifndef::tbtc[toc::[]] -The price oracle is an integral part of the system, ensuring sufficient collateral backs all tBTC signers. We model the oracle after the https://developer.makerdao.com/feeds/[USD price feeds from MakerDAO], operated initially by a single trusted actor and later governed by the ecosystem. +The price feed is an integral part of the system, ensuring sufficient collateral backs all tBTC signers. We model the feed after the https://developer.makerdao.com/feeds/[USD price feeds from MakerDAO], operated initially by a single trusted actor and later governed by the ecosystem. The minimal price feed design is specified completely by the interface below: @@ -29,22 +29,22 @@ This mitigates unnecessary recomputations by maintainers for price changes below == Price encoding -A bitcoin has 8 decimal places, the smallest unit being a satoshi, meaning 100 000 000 satoshis = 1 bitcoin. -An ether by contrast, has 18 decimal places, the smallest unit being a wei, meaning -1 000 000 000 000 000 000 wei = 1 ether. +A bitcoin has 8 decimal places, the smallest unit being a satoshi, meaning 100 000 000 satoshis = 1 bitcoin. +An ether by contrast, has 18 decimal places, the smallest unit being a wei, meaning +1 000 000 000 000 000 000 wei = 1 ether. -To express the price of bitcoin relative to ether, we must use a ratio of the number of wei to a satoshi. -A simple design is to use `x` wei : 1 satoshi. Hence, for a call to `getPrice` when 32.32 ETH : 1 BTC (Jun 2019), -the value 323 200 000 000 wei is returned. +To express the price of bitcoin relative to ether, we must use a ratio of the number of wei to a satoshi. +A simple design is to use `x` wei : 1 satoshi. Hence, for a call to `getPrice` when 32.32 ETH : 1 BTC (Jun 2019), +the value 323 200 000 000 wei is returned. -However, if 1 wei is worth more than 1 sat, then the price can no longer be accurately encoded. This scenario of a 'flippening', -when 1 ether becomes worth 10,000,000,000x as much as 1 bitcoin, we find unlikely in the very short-term. -Rather than prematurely optimize, incorporating a 2 integer ratio of `x` wei to `y` satoshi and changing the call semantics, +However, if 1 wei is worth more than 1 sat, then the price can no longer be accurately encoded. This scenario of a 'flippening', +when 1 ether becomes worth 10,000,000,000x as much as 1 bitcoin, we find unlikely in the very short-term. +Rather than prematurely optimize, incorporating a 2 integer ratio of `x` wei to `y` satoshi and changing the call semantics, we leave this as a future exercise for governance. == Future design -The price oracle is integral to tBTC's security and in the future, will be principally governed by -the tBTC ecosystem. The first upgrades will focus on incorporating a medianizer model from MakerDAO, where +The price feed is integral to tBTC's security and in the future, will be principally governed by +the tBTC ecosystem. The first upgrades will focus on incorporating a medianizer model from MakerDAO, where multiple price feeds are voted in and the median price is calculated from their reports. Other on-chain price signals like -decentralized exchanges (DEX's) and liquidity pools (Uniswap) are being considered. \ No newline at end of file +decentralized exchanges (DEX's) and liquidity pools (Uniswap) are being considered.