Merge pull request #333 from keep-network/no-oracle

Stop using "oracle" because it's a loaded word

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*

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*

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 <<Custodial Fees>> 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
-<<price-oracle/index.adoc#price-oracle,price oracle>>.
+<<price-feed/index.adoc#price-feed,price feed>>.
 
 == Undercollateralization
 

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]
 

docs/price-oracle/index.adoc → 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.
+decentralized exchanges (DEX's) and liquidity pools (Uniswap) are being considered.