MakerDAO-Abacus
MakerDAO Abacus 合约分析
// SPDX-License-Identifier: AGPL-3.0-or-later
/// abaci.sol -- price decrease functions for auctions
// Copyright (C) 2020-2022 Dai Foundation
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published
// by the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
pragma solidity ^0.6.12;
interface Abacus {
// 1st arg: initial price [ray] 初始价格
// 2nd arg: seconds since auction start [seconds] 拍卖开始后的秒数
// returns: current auction price [ray] 当前拍卖价格
function price(uint256, uint256) external view returns (uint256);
}
/**
* @title 线性下降合约
* @author
* @notice 用于计算线性下降的价格
*/
contract LinearDecrease is Abacus {
// --- Auth ---
mapping(address => uint256) public wards;
function rely(address usr) external auth {
wards[usr] = 1;
emit Rely(usr);
}
function deny(address usr) external auth {
wards[usr] = 0;
emit Deny(usr);
}
modifier auth() {
require(wards[msg.sender] == 1, "LinearDecrease/not-authorized");
_;
}
// --- Data ---
// 拍卖开始后价格归零后的秒数 [seconds]
uint256 public tau; // Seconds after auction start when the price reaches zero [seconds]
// --- Events ---
event Rely(address indexed usr);
event Deny(address indexed usr);
event File(bytes32 indexed what, uint256 data);
// --- Init ---
constructor() public {
wards[msg.sender] = 1;
emit Rely(msg.sender);
}
// --- Administration ---
/**
*
* @param what 要修改的数据，该函数 `what` 参数只能是 `tau`
* @param data 将 `tau` 修改为 `data`
*/
function file(bytes32 what, uint256 data) external auth {
if (what == "tau") tau = data;
else revert("LinearDecrease/file-unrecognized-param");
emit File(what, data);
}
// --- Math ---
uint256 constant RAY = 10 ** 27;
function add(uint256 x, uint256 y) internal pure returns (uint256 z) {
require((z = x + y) >= x);
}
function mul(uint256 x, uint256 y) internal pure returns (uint256 z) {
require(y == 0 || (z = x * y) / y == x);
}
/// @dev 固定点乘法函数，将两个定点数相乘，并且将结果缩放回来。
/// @notice 该函数用于计算两个单位为 ray（10^27） 的数相乘
function rmul(uint256 x, uint256 y) internal pure returns (uint256 z) {
z = x * y;
require(y == 0 || z / y == x);
z = z / RAY;
}
// Price calculation when price is decreased linearly in proportion to time:
// tau: The number of seconds after the start of the auction where the price will hit 0
// top: Initial price
// dur: current seconds since the start of the auction
//
// Returns y = top * ((tau - dur) / tau)
//
// Note the internal call to mul multiples by RAY, thereby ensuring that the rmul calculation
// which utilizes top and tau (RAY values) is also a RAY value.
/**
* @dev 计算开始拍卖后对应秒数之后的价格
* @param top 初始价格
* @param dur 拍卖开始后的经历秒数
* @return `y = top * ((tau - dur) / tau)
* @notice RAY 内部调用了 mul 倍数，从而确保利用 top 和 tau（RAY 值）的 rmul 计算也是 RAY 值。
*/
function price(uint256 top, uint256 dur) external view override returns (uint256) {
// `tau` 拍卖开始后价格降至 0 所需的秒数 [seconds]
if (dur >= tau) return 0;
return rmul(top, mul(tau - dur, RAY) / tau);
}
}
/**
* @title 阶梯式指数下降合约
* @author
* @notice
* - 此合约返回有效价格
* - `cut` 和 `step` 值必须正确设置
*/
contract StairstepExponentialDecrease is Abacus {
// --- Auth ---
mapping(address => uint256) public wards;
function rely(address usr) external auth {
wards[usr] = 1;
emit Rely(usr);
}
function deny(address usr) external auth {
wards[usr] = 0;
emit Deny(usr);
}
modifier auth() {
require(wards[msg.sender] == 1, "StairstepExponentialDecrease/not-authorized");
_;
}
// --- Data ---
uint256 public step; // Length of time between price drops [seconds] 价格下跌间隔时间
uint256 public cut; // Per-step multiplicative factor [ray] 每单位间隔时间的乘数因子 [ray]
// --- Events ---
event Rely(address indexed usr);
event Deny(address indexed usr);
event File(bytes32 indexed what, uint256 data);
// --- Init ---
// this contract to return a valid price 此合约返回有效价格
// @notice: `cut` and `step` values must be correctly set for `cut` 和 `step` 值必须正确设置
constructor() public {
wards[msg.sender] = 1;
emit Rely(msg.sender);
}
// --- Administration ---
/**
* @dev 访问权限控制函数，修改系统参数
* @param what 在本合约中，`what` 的参数有两个：`cut` 和 `step` ;若 `what == "cut"`,data 需要以 ray 为单位
* @param data 将对应参数修改为的值
*/
function file(bytes32 what, uint256 data) external auth {
if (what == "cut") require((cut = data) <= RAY, "StairstepExponentialDecrease/cut-gt-RAY");
else if (what == "step") step = data;
else revert("StairstepExponentialDecrease/file-unrecognized-param");
emit File(what, data);
}
// --- Math ---
uint256 constant RAY = 10 ** 27;
function rmul(uint256 x, uint256 y) internal pure returns (uint256 z) {
z = x * y;
require(y == 0 || z / y == x);
z = z / RAY;
}
// optimized version from dss PR #78
/**
* @dev 固定点数的幂运算
* @param x 底数
* @param n 指数
* @param b 基数，缩放结果
* @return z 幂运算的结果
*/
function rpow(uint256 x, uint256 n, uint256 b) internal pure returns (uint256 z) {
assembly {
switch n
case 0 { z := b }
default {
switch x
case 0 { z := 0 }
default {
switch mod(n, 2)
// 采取快速幂算法
case 0 { z := b }
default { z := x }
let half := div(b, 2) // for rounding.
for { n := div(n, 2) } n { n := div(n, 2) } {
let xx := mul(x, x)
if shr(128, x) { revert(0, 0) }
let xxRound := add(xx, half)
if lt(xxRound, xx) { revert(0, 0) }
x := div(xxRound, b)
if mod(n, 2) {
let zx := mul(z, x)
if and(iszero(iszero(x)), iszero(eq(div(zx, x), z))) { revert(0, 0) }
let zxRound := add(zx, half)
if lt(zxRound, zx) { revert(0, 0) }
z := div(zxRound, b)
}
}
}
}
}
}
// top: initial price
// dur: seconds since the auction has started
// step: seconds between a price drop
// cut: cut encodes the percentage to decrease per step.
// For efficiency, the values is set as (1 - (% value / 100)) * RAY
// So, for a 1% decrease per step, cut would be (1 - 0.01) * RAY
//
// returns: top * (cut ^ dur)
//
//
/**
* @notice
* - 计算开始拍卖后对应秒数之后的价格
* - step：一次降低价格的间隔秒数
* - cut：每单位价格下降间隔秒数减少的百分比
* 为了提高效率，值设置为 (1 -(% value / 100)) * RAY
* 因此，每 step 减少 1%，cut 将是 (1- 0.01) * RAY
* @param top 初始价格
* @param dur 拍卖开始后经历的秒数
* @return `top * (cut ^ dur)`
*/
function price(uint256 top, uint256 dur) external view override returns (uint256) {
return rmul(top, rpow(cut, dur / step, RAY));
// top * cut * cut * cut …… (cut number = dur / strp)
}
}
// While an equivalent function can be obtained by setting step = 1 in StairstepExponentialDecrease,
// this continous (i.e. per-second) exponential decrease has be implemented as it is more gas-efficient
// than using the stairstep version with step = 1 (primarily due to 1 fewer SLOAD per price calculation).
/**
* @title 指数下降合约
* @author
* @notice
* - 虽然可以通过在 StairstepExponentialDecrease 中设置 `step = 1` 来获得等效函数，
* 但这种连续（即每秒）指数下降已被实现，因为它比使用 `step = 1` 的阶梯版本更节省 gas
* （主要是因为每次价格计算的 SLOAD 少 1 个）。
* - `cut` 和 `step` 值必须正确设置
* - 此合约返回有效价格
*/
contract ExponentialDecrease is Abacus {
// --- Auth ---
mapping(address => uint256) public wards;
function rely(address usr) external auth {
wards[usr] = 1;
emit Rely(usr);
}
function deny(address usr) external auth {
wards[usr] = 0;
emit Deny(usr);
}
modifier auth() {
require(wards[msg.sender] == 1, "ExponentialDecrease/not-authorized");
_;
}
// --- Data ---
uint256 public cut; // Per-second multiplicative factor [ray] 每秒的乘数因子 [ray]
// --- Events ---
event Rely(address indexed usr);
event Deny(address indexed usr);
event File(bytes32 indexed what, uint256 data);
// --- Init ---
// @notice: `cut` value must be correctly set for `cut`的值必须正确设置
// this contract to return a valid price 此合约返回有效价格
constructor() public {
wards[msg.sender] = 1;
emit Rely(msg.sender);
}
// --- Administration ---
/**
* @dev 访问权限控制函数，修改系统参数
* @param what 在本合约中，`what` 的参数只能是`cut`
* @param data 将对应参数修改为的值，在本合约中，`data`必须以 ray 为单位
*/
function file(bytes32 what, uint256 data) external auth {
if (what == "cut") require((cut = data) <= RAY, "ExponentialDecrease/cut-gt-RAY");
else revert("ExponentialDecrease/file-unrecognized-param");
emit File(what, data);
}
// --- Math ---
uint256 constant RAY = 10 ** 27;
function rmul(uint256 x, uint256 y) internal pure returns (uint256 z) {
z = x * y;
require(y == 0 || z / y == x);
z = z / RAY;
}
// optimized version from dss PR #78
/**
* @dev 固定点数的幂运算
* @param x 底数
* @param n 指数
* @param b 基数，缩放结果
* @return z 幂运算的结果
*/
function rpow(uint256 x, uint256 n, uint256 b) internal pure returns (uint256 z) {
assembly {
switch n
case 0 { z := b }
default {
switch x
case 0 { z := 0 }
default {
switch mod(n, 2)
case 0 { z := b }
default { z := x }
let half := div(b, 2) // for rounding.
for { n := div(n, 2) } n { n := div(n, 2) } {
let xx := mul(x, x)
if shr(128, x) { revert(0, 0) }
let xxRound := add(xx, half)
if lt(xxRound, xx) { revert(0, 0) }
x := div(xxRound, b)
if mod(n, 2) {
let zx := mul(z, x)
if and(iszero(iszero(x)), iszero(eq(div(zx, x), z))) { revert(0, 0) }
let zxRound := add(zx, half)
if lt(zxRound, zx) { revert(0, 0) }
z := div(zxRound, b)
}
}
}
}
}
}
// top: initial price
// dur: seconds since the auction has started
// cut: cut encodes the percentage to decrease per second.
// For efficiency, the values is set as (1 - (% value / 100)) * RAY
// So, for a 1% decrease per second, cut would be (1 - 0.01) * RAY
//
// returns: top * (cut ^ dur)
//
/**
* @notice
* - 计算开始拍卖后对应秒数之后的价格
* - cut：每秒数减少的百分比
* 为了提高效率，值设置为 (1 -(% value / 100)) * RAY
* 因此，每秒减少 1%，cut 将是 (1- 0.01) * RAY
* @param top 初始价格
* @param dur 拍卖开始后经历的秒数
* @return `top * (cut ^ dur)`
*/
function price(uint256 top, uint256 dur) external view override returns (uint256) {
return rmul(top, rpow(cut, dur, RAY));
}
}
本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 Q1ngying！