From 5f8dd7bd287108ed5aa37bcd316569f7a2370850 Mon Sep 17 00:00:00 2001 From: James Prestwich Date: Tue, 5 Nov 2019 09:30:01 -0800 Subject: [PATCH] remove the word 'oracle' from docs. clarify that it things called 'oracle' are either a price feed or a difficulty relay --- docs/appendix/states/failure.adoc | 6 ++-- docs/appendix/states/redemption.adoc | 4 +-- docs/bonding/index.adoc | 30 ++++++++++---------- docs/index.adoc | 2 +- docs/{price-oracle => price-feed}/index.adoc | 30 ++++++++++---------- 5 files changed, 36 insertions(+), 36 deletions(-) rename docs/{price-oracle => price-feed}/index.adoc (67%) 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 9d6d97ad1..69ee3a8d6 100644 --- a/docs/bonding/index.adoc +++ b/docs/bonding/index.adoc @@ -61,7 +61,7 @@ the two currencies fluctuate relative to each other, sometimes wildly. If the value of ETH drops precipitously relative to BTC, then the dollar value of the ETH bonded by the signers can be less than the dollar value of the BTC Deposit they have backed, meaning they have positive expected value if they try -to steal the BTC. +to steal the BTC. In order to avoid that, we require that the bonds are overcollateralized. For each ETH they collateralize, they must put up an additional {extracollateral}, for a total of @@ -88,25 +88,25 @@ the expense of opportunity cost to the Signers which should be compensated via f If the value of ETH crosses a security threshold, open _Deposit_ s will enter <>, followed by <> if they do not top 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 overcollateralization factored in), a BTC value drop against the bonded asset translates in lower fees for Signers. Note that this does not create any issue for tBTC reserves, but it makes the system less attractive to signers looking to earn interest via fees on their assets. -Signers SHOULD buy TBTC from the markets in anticipation of such overly +Signers SHOULD buy TBTC from the markets in anticipation of such overly overcollateralized Deposits and they SHOULD use it to redeem these positions, thus reclaiming their ETH liquidity which can be used to back other Deposits. An alternative would be to provide Signers with the ability to safely rebalance their bonds back to {totalcollateral}, however that introduces implementation complexities and as a result is not the preferred solution for the initial deployment of the mechanism. - + Example: Let 1 BTC be worth $10,000, and 1 ETH be worth $200. Signers have to put up 75 ETH to back a deposit. Signers are expected to make a custodial fee of 5 basis @@ -118,7 +118,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 @@ -126,11 +126,11 @@ the market. Instead, the goal is to ensure that the TBTC supply is strictly less than its backing BTC reserves. For this reason, the only price relationship the system needs to understand is -between the signing bond collateral and BTC. +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 -<>. +prices for a single pair of assets, tBTC will initially use a simple +<>. == Undercollateralization @@ -151,7 +151,7 @@ liquidation will follow. This gives each signer an incentive to close the position before it becomes severely undercollateralized. Alternatively, if the ETHBTC ratio recovers such that the deposit becomes at least {first-threshold} collateralized during the {preliquidation-period} the Deposit is safe and is -moved away from the pre-liquidation state. +moved away from the pre-liquidation state. In future versions of the system, more complex pre-liquidation mechanisms could be introduced. For the initial version it seems prudent to choose a simple @@ -170,7 +170,7 @@ punishment via liquidation is necessary to prevent dishonest behavior from signers. Liquidation may occur because because signers didn't produce a valid signature in response a redemption request, because the value of the signing bond dropped below the liquidation threshold, because they did not respond to the -courtesy call, or because the signers produced a fraudulent signature. +courtesy call, or because the signers produced a fraudulent signature. // comment(Georgios): What does unauthorized signature mean here? The primary goal of the liquidation process is to bring the TBTC supply in line @@ -179,7 +179,7 @@ system is the signers' bonds. Therefore, the liquidation process seizes the signers bonds and attempts to use the bonded value to purchase and burn TBTC. First, the contract attempts to use on-chain liquidity sources, such as -https://hackmd.io/@477aQ9OrQTCbVR3fq1Qzxg/HJ9jLsfTz[Uniswap]. +https://hackmd.io/@477aQ9OrQTCbVR3fq1Qzxg/HJ9jLsfTz[Uniswap]. If the bond is sufficient to cover the outstanding TBTC value on these markets, it is immediately exchanged for TBTC. @@ -200,7 +200,7 @@ What the unresponsive signers do with the BTC outside the tBTC system design is for them to decide-- it might be split up, stolen by a signing majority, or lost permanently. -Example: +Example: 1. Signers guard a deposit of 1 BTC, backed by 75 ETH at 0.02 BTC/ETH (1.5 BTC in ETH, 150% collateralization ratio). @@ -225,4 +225,4 @@ liquidation of the Deposit is now over. fraud it'd be burned), and 0.1 ETH is given to the account which called the liquidation function on the Ethereum smart contract. -1. The N signers coordinate and agree on how they will distribute the 1 BTC deposit. \ No newline at end of file +1. The N signers coordinate and agree on how they will distribute the 1 BTC deposit. diff --git a/docs/index.adoc b/docs/index.adoc index 6080b31e4..b0ad1ea53 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -250,7 +250,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::custodial-fees/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.