counter simulator 2022

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+env:
+  FOUNDRY_PROFILE: ci
+
+jobs:
+  run-ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
+
+      - name: Install deps
+        run: forge install
+
+      - name: Run tests
+        run: forge test

.gitignore

@@ -0,0 +1,3 @@
+out/
+cache/
+.vscode/

.gitmodules

@@ -0,0 +1,12 @@
+[submodule "lib/forge-std"]
+	path = lib/forge-std
+	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/ds-token"]
+	path = lib/ds-token
+	url = https://github.com/dapphub/ds-token
+[submodule "lib/ds-note"]
+	path = lib/ds-note
+	url = https://github.com/dapphub/ds-note
+[submodule "lib/ds-auth"]
+	path = lib/ds-auth
+	url = https://github.com/dapphub/ds-auth

README.md

@@ -0,0 +1,139 @@
+# Decentralized Summation System
+
+This repository contains the core smart contract code for the Decentralized
+Summation System (`dss`). This is a high level description of the system, assuming
+familiarity with the basic counting mechanics as described in the
+whitepaper.
+
+## System Diagram
+
+![DSS System Diagram](/doc/dss-diagram.png?raw=true)
+
+## Design Considerations
+
+- Client agnostic
+  - system doesn't care about the implementation of external contracts
+  - can operate entirely independently of other systems
+
+- Verifiable
+  - designed from the bottom up to be amenable to formal verification
+  - the core ICV and counter database makes *no* external calls and
+    contains *no* precision loss (i.e. no division)
+
+- Modular
+  - multi contract core system is made to be very adaptable to changing
+    requirements.
+  - allows for the addition of novel counter types (e.g. count-by-threes, fibonacci)
+
+## Usage
+
+See the test cases in [`dss.t.sol`](https://github.com/counterdao/dss/blob/aa7809965a314a5c8fdf7e6b5d39a92bf0901c3f/test/dss.t.sol#L76) for annotated examples that demonstrate how to interact with `dss` from your own contracts.
+
+## Sum — Counter Engine
+
+The `Sum` is the core Counter engine of `dss`. It stores Counters and tracks
+all the associated values. It also defines the rules by which Counters and values
+can be manipulated. The rules defined in the `Sum` are immutable, so in some
+sense, the rules in the `Sum` can be viewed as the constitution of `dss`.
+
+Within the `Sum` an `Inc` represents a stored ICV (Integer Counter Value). The
+attributes of an `Inc` are:
+- `net`: The counter value.
+- `tab`: The sum of all counter increments.
+- `tax`: The sum of all counter decrements.
+- `num`: Total number of counter operations, i.e. sum of increments, decrements, and resets.
+- `hop`: The counter's increment unit.
+
+Functions:
+- `boot`: Register a new Counter.
+- `zero`: Reset a Counter.
+- `frob`: General function for manipulating a Counter.
+  - `sinc`: "Sign of increment." 1 for increment, -1 for decrement.
+- `wish`: Check whether an address is allowed to modify another address's Counter.
+  - `hope`: enable `wish` for a pair of addresses.
+  - `nope`: disable `wish` for a pair of addresses.
+
+## Hitter — Increment module
+
+The `Hitter` is used to increment an initialized Counter.
+
+Functions:
+- `hit`: Increases a Counter's `net` and `tab` by one `hop`. Increments `num`.
+
+## Dipper — Decrement module
+
+The `Dipper` is used to decrement an initialized Counter.
+
+Functions:
+- `dip`: Decreases a Counter's `net` and `tax` by one `hop`. Increments `num`.
+
+## Nil — Reset module
+
+`Nil` is used to reset an initialized counter.
+
+Functions:
+- `nil`: Resets a Counter's `net`, `tab`, and `tax` to zero. Increments `num`.
+
+## Spy — Counter read module
+
+The `Spy` is used to read counter values.
+
+Functions:
+- `see`: Returns a Counter's `net`. View only function.
+
+## DSS — Protocol interface module
+
+The `DSS` module is an interface contract that composes other modules in
+the `dss` system and provides a unified interface to the protocol.
+
+Functions:
+- `build`: Create a new `DSSProxy` with this `DSS` module as its target implementation. Authorizes
+  `msg.sender` to interact with the proxy.
+  - `wit`: A `bytes32` salt for the `create2` constructor.
+  - `god`: Proxy owner address, authorized to update the implementation and manage `wards`.
+- `bless`: Authorize the core `dss` modules (`Use`, `Hitter`, `Dipper`, and `Nil`).
+- `use`: Create a new Counter.
+- `see`: Read a Counter value.
+- `hit`: Increment a Counter.
+- `dip`: Decrement a Counter.
+- `nil`: Reset a Counter.
+- `hope`: Authorize a module to manipulate a Counter.
+- `nope`: Revoke a module's authorization. This may be used to customize Counter
+  behavior, e.g. disabling decrements and resets.
+
+In most cases users should not interact directly with the `DSS` module, but instead use a `DSSProxy`.
+
+## DSSProxy — Execute DSS actions
+
+A `DSSProxy` is a transparent proxy contract that targets the `DSS` interface module as its
+implementation. This enables callers to execute DSS actions through a persistent identity.
+In most cases, users should create and interact with Counters through a `DSSProxy`.
+
+In the event of a protocol upgrade, the `DSSProxy` owner may choose to `upgrade` their proxy to
+target the latest `DSS` interface module.
+
+`DSSProxy` includes a flexible authorization mechanism that allows multiple callers to interact
+with a Counter through the proxy's persistent identity. This enables the creation of Counters
+that may be shared by multiple contracts simultaneously, or used by many different contracts
+over time.
+
+Functions:
+- `upgrade`: Set a new address as the target implementation. Only callable by the proxy `owner`
+- `rely`: Authorize an address to call the proxy and interact with a Counter.
+- `deny`: Revoke authorization from an address.
+
+## System parameters
+
+CTR token holders govern the core parameter of the DSS protocol, namely `One`.
+The value of `One` represents the global counter increment unit. Newly initialized Counters
+store the active `One` as their `hop` at creation time.
+
+**Note:** The value of `One` is a **critical** system parameter and **must be set carefully by governance**.
+An incorrect value of `One` may have unintended and far reaching consequences for
+the DSS protocol and the systems that depend on it.
+
+## Acknowledgments
+
+- [shrugs](https://github.com/shrugs), author of the one and only[`Counters.sol`](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/Counters.sol).
+- [karmacoma](https://github.com/karmacoma-eth), for creating [`enterprise-counters`](https://github.com/karmacoma-eth/enterprise-counters) and putting me up to this.
+- [dapphub](https://github.com/dapphub) and [Maker](https://github.com/makerdao) for the greatest contracts of all time.

foundry.toml

@@ -0,0 +1,6 @@
+[profile.default]
+src = 'src'
+out = 'out'
+libs = ['lib']
+
+# See more config options https://github.com/foundry-rs/foundry/tree/master/config

src/dip.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/// dip.sol -- Counter decrement module
+
+// Copyright (C) 2022 Horsefacts <[email protected]>
+//
+// 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.8.15;
+
+interface SumLike {
+    function frob(address,int) external;
+}
+
+contract Dipper {
+    // --- Data ---
+    SumLike immutable public sum;
+
+    // --- Init ---
+    constructor(address sum_) {
+        sum = SumLike(sum_);
+    }
+
+    // --- Counter Decrement ---
+    function dip() external {
+        sum.frob(msg.sender, -1);
+    }
+}

src/dss.sol

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/// dss.sol -- Decentralized Summation System
+
+// Copyright (C) 2022 Horsefacts <[email protected]>
+//
+// 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.8.15;
+
+import {DSSProxy} from "./proxy/proxy.sol";
+
+interface DSSLike {
+    function use() external;
+    function see() external view returns (uint256);
+    function hit() external;
+    function dip() external;
+    function nil() external;
+    function hope(address) external;
+    function nope(address) external;
+    function bless() external;
+}
+
+interface SumLike {
+    function hope(address) external;
+    function nope(address) external;
+}
+
+interface UseLike {
+    function use() external;
+}
+
+interface SpyLike {
+    function see() external view returns (uint256);
+}
+
+interface HitterLike {
+    function hit() external;
+}
+
+interface DipperLike {
+    function dip() external;
+}
+
+interface NilLike {
+    function nil() external;
+}
+
+contract DSS {
+    // --- Data ---
+    SumLike    immutable public _sum;
+    UseLike    immutable public _use;
+    SpyLike    immutable public _spy;
+    HitterLike immutable public _hitter;
+    DipperLike immutable public _dipper;
+    NilLike    immutable public _nil;
+
+    // --- Init ---
+    constructor(
+        address sum_,
+        address use_,
+        address spy_,
+        address hitter_,
+        address dipper_,
+        address nil_)
+    {
+        _sum    = SumLike(sum_);        // Core ICV engine
+        _use    = UseLike(use_);        // Creation module
+        _spy    = SpyLike(spy_);        // Read module
+        _hitter = HitterLike(hitter_);  // Increment module
+        _dipper = DipperLike(dipper_);  // Decrement module
+        _nil    = NilLike(nil_);        // Reset module
+    }
+
+    // --- DSS Operations ---
+    function use() external {
+        _use.use();
+    }
+
+    function see() external view returns (uint256) {
+        return _spy.see();
+    }
+
+    function hit() external {
+        _hitter.hit();
+    }
+
+    function dip() external {
+        _dipper.dip();
+    }
+
+    function nil() external {
+        _nil.nil();
+    }
+
+    function hope(address usr) external {
+        _sum.hope(usr);
+    }
+
+    function nope(address usr) external {
+        _sum.nope(usr);
+    }
+
+    function bless() external {
+        _sum.hope(address(_use));
+        _sum.hope(address(_hitter));
+        _sum.hope(address(_dipper));
+        _sum.hope(address(_nil));
+    }
+
+    function build(bytes32 wit, address god) external returns (address proxy) {
+        proxy = address(new DSSProxy{ salt: wit }(address(this), msg.sender, god));
+    }
+}

src/gov/ctr.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/// ctr.sol -- Counter governance token
+
+// Copyright (C) 2022 Horsefacts <[email protected]>
+// Copyright (C) 2015, 2016, 2017  DappHub, LLC
+//
+// 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.4.23 <0.7.0;
+
+import {DSToken} from "ds-token/token.sol";
+
+contract CTR is DSToken {
+
+    constructor() DSToken("CTR") public {
+        setName("Counter");
+        mint(msg.sender, 1_000_000 ether);
+    }
+
+}