oikos-v3

This is the code for Oikos smart contracts.

Repo Guide

Branching

A note on the branches used in this repo.

• master represents the contracts live on mainnet and all testnets.

When a new version of the contracts makes its way through all testnets, it eventually becomes promoted in master, with semver reflecting contract changes in the major or minor portion of the version (depending on backwards compatibility). patch changes are simply for changes to the JavaScript interface.

Testing

Please see docs.oikos.cash/contracts/testing for an overview of the automated testing methodologies.

Module Usage

This repo may be installed via npm install to support both node.js scripting applications and Solidity contract development.

Examples

:100: Please see our walkthroughs for code examples in both JavaScript and Solidity: docs.oikos.cash/integrations

Solidity API

All interfaces are available via the path oikos/contracts/interfaces.

:zap: In your code, the key is to use IAddressResolver which can be tied to the immutable proxy: ReadProxyAddressResolver. You can then fetch Oikos, FeePool, Depot, et al via IAddressResolver.getAddress(bytes32 name) where name is the bytes32 version of the contract name (case-sensitive). Or you can fetch any synth using IAddressResolver.getSynth(bytes32 synth) where synth is the bytes32 name of the synth (e.g. iETH, oUSD, sDEFI).

E.g.

npm install oikos-v3

then you can write Solidity as below (using a compiler that links named imports via node_modules):

pragma solidity 0.5.16;

import 'oikos/contracts/interfaces/IAddressResolver.sol';
import 'oikos/contracts/interfaces/IOikos.sol';

contract MyContract {
  // This should be instantiated with our ReadProxyAddressResolver
  // it's a ReadProxy that won't change, so safe to code it here without a setter
  // see https://docs.oikos.cash/addresses for addresses in mainnet and testnets
  IAddressResolver public oikosResolver;

  constructor(IAddressResolver _oksResolver) public {
    oikosResolver = _oksResolver;
  }

  function oikosIssue() external {
    IOikos oikos = oikosResolver.getAddress('Oikos');
    require(oikos != address(0), 'Oikos is missing from Oikos resolver');

    // Issue for msg.sender = address(MyContract)
    oikos.issueMaxSynths();
  }

  function oikosIssueOnBehalf(address user) external {
    IOikos oikos = oikosResolver.getAddress('Oikos');
    require(oikos != address(0), 'Oikos is missing from Oikos resolver');

    // Note: this will fail if `DelegateApprovals.approveIssueOnBehalf(address(MyContract))` has
    // not yet been invoked by the `user`
    oikos.issueMaxSynthsOnBehalf(user);
  }
}

Node.js API

• getAST({ source, match = /^contracts\// }) Returns the Abstract Syntax Tree (AST) for all compiled sources. Optionally add source to restrict to a single contract source, and set match to an empty regex if you'd like all source ASTs including third party contracts
• getPathToNetwork({ network, file = '' }) Returns the path to the folder (or file within the folder) for the given network
• getSource({ network }) Return abi and bytecode for a contract source
• getSuspensionReasons({ code }) Return mapping of SystemStatus suspension codes to string reasons
• getStakingRewards({ network }) Return the list of staking reward contracts available.
• getSynths({ network }) Return the list of synths for a network
• getTarget({ network }) Return the information about a contract's address and source file. The contract names are those specified in docs.oikos.cash/addresses
• getTokens({ network }) Return the list of tokens (synths and SNX) used in the system, along with their addresses.
• getUsers({ network }) Return the list of user accounts within the Oikos protocol (e.g. owner, fee, etc)
• getVersions({ network, byContract = false }) Return the list of deployed versions to the network keyed by tagged version. If byContract is true, it keys by contract name.
• networks Return the list of supported networks
• toBytes32 Convert any string to a bytes32 value

Via code

const oks = require('oikos');

oks.getAST();
/*
{ 'contracts/AddressResolver.sol':
   { imports:
      [ 'contracts/Owned.sol',
        'contracts/interfaces/IAddressResolver.sol',
        'contracts/interfaces/IOikos.sol' ],
     contracts: { AddressResolver: [Object] },
     interfaces: {},
     libraries: {} },
  'contracts/Owned.sol':
   { imports: [],
     contracts: { Owned: [Object] },
     interfaces: {},
     libraries: {} },
*/

oks.getAST({ source: 'Oikos.sol' });
/*
{ imports:
   [ 'contracts/ExternStateToken.sol',
     'contracts/MixinResolver.sol',
     'contracts/interfaces/IOikos.sol',
     'contracts/TokenState.sol',
     'contracts/interfaces/ISynth.sol',
     'contracts/interfaces/IERC20.sol',
     'contracts/interfaces/ISystemStatus.sol',
     'contracts/interfaces/IExchanger.sol',
     'contracts/interfaces/IIssuer.sol',
     'contracts/interfaces/IOikosState.sol',
     'contracts/interfaces/IExchangeRates.sol',
     'contracts/SupplySchedule.sol',
     'contracts/interfaces/IRewardEscrow.sol',
     'contracts/interfaces/IHasBalance.sol',
     'contracts/interfaces/IRewardsDistribution.sol' ],
  contracts:
   { Oikos:
      { functions: [Array],
        events: [Array],
        variables: [Array],
        modifiers: [Array],
        structs: [],
        inherits: [Array] } },
  interfaces: {},
  libraries: {} }
*/

// Get the path to the network
oks.getPathToNetwork({ network: 'mainnet' });
//'.../Oikosio/oikos/publish/deployed/mainnet'

// retrieve an object detailing the contract ABI and bytecode
oks.getSource({ network: 'rinkeby', contract: 'Proxy' });
/*
{
  bytecode: '0..0',
  abi: [ ... ]
}
*/

oks.getSuspensionReasons();
/*
{
	1: 'System Upgrade',
	2: 'Market Closure',
	3: 'Circuit breaker',
	99: 'Emergency',
};
*/

// retrieve the array of synths used
oks.getSynths({ network: 'rinkeby' }).map(({ name }) => name);
// ['oUSD', 'sEUR', ...]

// retrieve an object detailing the contract deployed to the given network.
oks.getTarget({ network: 'rinkeby', contract: 'ProxyOikos' });
/*
{
	name: 'ProxyOikos',
  address: '0x322A3346bf24363f451164d96A5b5cd5A7F4c337',
  source: 'Proxy',
  link: 'https://rinkeby.etherscan.io/address/0x322A3346bf24363f451164d96A5b5cd5A7F4c337',
  timestamp: '2019-03-06T23:05:43.914Z',
  txn: '',
	network: 'rinkeby'
}
*/

// retrieve the list of system user addresses
oks.getUsers({ network: 'mainnet' });
/*
[ { name: 'owner',
    address: '0xEb3107117FEAd7de89Cd14D463D340A2E6917769' },
  { name: 'deployer',
    address: '0xDe910777C787903F78C89e7a0bf7F4C435cBB1Fe' },
  { name: 'marketClosure',
    address: '0xC105Ea57Eb434Fbe44690d7Dec2702e4a2FBFCf7' },
  { name: 'oracle',
    address: '0xaC1ED4Fabbd5204E02950D68b6FC8c446AC95362' },
  { name: 'fee',
    address: '0xfeEFEEfeefEeFeefEEFEEfEeFeefEEFeeFEEFEeF' },
  { name: 'zero',
    address: '0x0000000000000000000000000000000000000000' } ]
*/

oks.getVersions();
/*
{ 'v2.21.12-107':
   { tag: 'v2.21.12-107',
     fulltag: 'v2.21.12-107',
     release: 'Hadar',
     network: 'kovan',
     date: '2020-05-08T12:52:06-04:00',
     commit: '19997724bc7eaceb902c523a6742e0bd74fc75cb',
		 contracts: { ReadProxyAddressResolver: [Object] }
		}
}
*/

oks.networks;
// [ 'local', 'kovan', 'rinkeby', 'ropsten', 'mainnet' ]

oks.toBytes32('oUSD');
// '0x7355534400000000000000000000000000000000000000000000000000000000'

As a CLI tool

Same as above but as a CLI tool that outputs JSON, using names without the get prefixes:

$ npx oikos ast contracts/Synth.sol
{
  "imports": [
    "contracts/Owned.sol",
    "contracts/ExternStateToken.sol",
    "contracts/MixinResolver.sol",
    "contracts/interfaces/ISynth.sol",
    "contracts/interfaces/IERC20.sol",
    "contracts/interfaces/ISystemStatus.sol",
    "contracts/interfaces/IFeePool.sol",
    "contracts/interfaces/IOikos.sol",
    "contracts/interfaces/IExchanger.sol",
    "contracts/interfaces/IIssue"
    # ...
  ]
}

$ npx oikos bytes32 oUSD
0x7355534400000000000000000000000000000000000000000000000000000000

$ npx oikos networks
[ 'local', 'kovan', 'rinkeby', 'ropsten', 'mainnet' ]

$ npx oikos source --network rinkeby --contract Proxy
{
  "bytecode": "0..0",
  "abi": [ ... ]
}

$ npx oikos suspension-reason --code 2
Market Closure

$ npx oikos synths --network rinkeby --key name
["oUSD", "sEUR", ... ]

$ npx oikos target --network rinkeby --contract ProxyOikos
{
  "name": "ProxyOikos",
  "address": "0x322A3346bf24363f451164d96A5b5cd5A7F4c337",
  "source": "Proxy",
  "link": "https://rinkeby.etherscan.io/address/0x322A3346bf24363f451164d96A5b5cd5A7F4c337",
  "timestamp": "2019-03-06T23:05:43.914Z",
  "network": "rinkeby"
}

$ npx oikos users --network mainnet --user oracle
{
  "name": "oracle",
  "address": "0xaC1ED4Fabbd5204E02950D68b6FC8c446AC95362"
}

$ npx oikos versions
{
  "v2.0-19": {
    "tag": "v2.0-19",
    "fulltag": "v2.0-19",
    "release": "",
    "network": "mainnet",
    "date": "2019-03-11T18:17:52-04:00",
    "commit": "eeb271f4fdd2e615f9dba90503f42b2cb9f9716e",
    "contracts": {
      "Depot": {
        "address": "0x172E09691DfBbC035E37c73B62095caa16Ee2388",
        "status": "replaced",
        "replaced_in": "v2.18.1"
      },
      "ExchangeRates": {
        "address": "0x73b172756BD5DDf0110Ba8D7b88816Eb639Eb21c",
        "status": "replaced",
        "replaced_in": "v2.1.11"
      },

      # ...

    }
  }
}

$ npx oikos versions --by-contract
{
  "Depot": [
    {
      "address": "0x172E09691DfBbC035E37c73B62095caa16Ee2388",
      "status": "replaced",
      "replaced_in": "v2.18.1"
    },
    {
      "address": "0xE1f64079aDa6Ef07b03982Ca34f1dD7152AA3b86",
      "status": "current"
    }
  ],
  "ExchangeRates": [
    {
      "address": "0x73b172756BD5DDf0110Ba8D7b88816Eb639Eb21c",
      "status": "replaced",
      "replaced_in": "v2.1.11"
    },

    # ...
  ],

  # ...
}