@dydxprotocol/solo

Ethereum Smart Contracts and TypeScript library used for the dYdX Solo Trading Protocol. Currently used by trade.dydx.exchange

Table of Contents

• Install
• Usage
• Contracts
• Security
• Development
• Maintainers
• Contributing
• License

Install

npm i -s @dydxprotocol/solo

Usage

Initialize

const solo = new Solo(
  provider,  // Valid web3 provider
  networkId, // Ethereum network ID (1 - Mainnet, 42 - Kovan, etc.)
);

Accounts

Solo is Account based. Each Account is referenced by its owner Ethereum address and an account number unique to that owner address. Accounts have balances on each asset supported by Solo, which can be either positive (indicating a net supply of the asset) or negative (indicating a net borrow of an asset). Accounts must maintain a certain level of collateralization or they will be liquidated.

Amounts

Amounts in Solo are denominated by 3 things:

• value the numerical value of the Amount
• reference One of:
  • AmountReference.Delta Indicates an amount relative to the existing balance
  • AmountReference.Target Indicates an absolute amount
• denomination One of:
  • AmountDenomination.Actual Indicates the amount is denominated in the actual units of the token being transferred
  • AmountDenomination.Principal Indicates the amount is denominated in principal. Solo uses these types of amount in its internal accounting, and they do not change over time

A very important thing to note is that amounts are always relative to how the balance of the Account being Operated on will change, not the amount of the Action occurring. So, for example you'd say [pseudocode] withdraw(-10), because when you Withdraw, the balance of the Account will decrease.

Markets

Solo has a Market for each ERC20 token asset it supports. Interest Each Market has a specified interest

Interest

Interest rates in Solo are dynamic and set per Market. Each interest rate is set based on the % utilization of that Market. Each Account's balances either continuously earns (if positive) or pays (if negative) interest.

Operations

Every state changing action to the protocol occurs through an Operation. Operations contain a series of Actions that each operate on an Account. Some examples of Actions include (but are not limited to): Deposits, Withdrawals, Buys, Sells, Trades, and Liquidates.

Importantly collateralization is only checked at the end of an operation, so accounts are allowed to be transiently undercollateralized in the scope of one Operation. This allows for Operations like a Sell -> Trade, where an asset is first sold, and the collateral is locked up as the second Action in the Operation.

Example

In this example 1 ETH is being withdrawn from an account, and then 200 DAI are being deposited into it:

await solo.token.setMaximumSoloAllowance(
  '0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359', // DAI Contract Address
  '0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5',
);

await solo.operation.initiate()
  .withdraw({
    primaryAccountOwner: '0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5',
    primaryAccountId: new BigNumber('123456'),
    marketId: new BigNumber(0), // WETH Market ID
    amount: {
      value: new BigNumber('-1e18'),
      reference: AmountReference.Delta,
      denomination: AmountDenomination.Actual,
    },
    to: '0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5'
  })
  .deposit({
    primaryAccountOwner: '0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5',
    primaryAccountId: new BigNumber('123456'),
    marketId: new BigNumber(1), // DAI Market ID
    amount: {
      value: new BigNumber('200e18'),
      reference: AmountReference.Delta,
      denomination: AmountDenomination.Actual,
    },
    from: '0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5',
  })
  .commit({
    from: '0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5',
    gasPrice: '1000000000',
    confirmationType: ConfirmationType.Confirmed,
  });

Web3

Solo uses web3 under the hood. You can access it through solo.web3

Contracts

Mainnet

Contract Name	Description	Address
SoloMargin	Main dYdX contract	0x1E0447b19BB6EcFdAe1e4AE1694b0C3659614e4e
PayableProxyForSoloMargin	WETH wrapper proxy	0xa8b39829cE2246f89B31C013b8Cde15506Fb9A76
PolynomialInterestSetter	Sets interest rates	0xad91a0ddf799176a0A87a32Dafe8F3dd28479918
Expiry	Handles account expiries	0x0ECE224FBC24D40B446c6a94a142dc41fAe76f2d
DaiPriceOracle	Price oracle for DAI	0x787F552BDC17332c98aA360748884513e3cB401a
WethPriceOracle	Price oracle for WETH	0xf61AE328463CD997C7b58e7045CdC613e1cFdb69
UsdcPriceOracle	Price oracle for USDC	0x52f1c952A48a4588f9ae615d38cfdbf8dF036e60
AdminImpl	SoloMargin library containing admin functions	0x8a6629fEba4196E0A61B8E8C94D4905e525bc055
OperationImpl	SoloMargin library containing operation functions	0x56E7d4520ABFECf10b38368b00723d9BD3c21ee1

Security

Independent Audits

The smart contracts were audited independently by both Zeppelin Solutions and Bramah Systems.

Code Coverage

All production smart contracts are tested and have 100% branching code-coverage.

Vulnerability Disclosure Policy

The disclosure of security vulnerabilities helps us ensure the security of our users.

How to report a security vulnerability?

If you believe you’ve found a security vulnerability in one of our contracts or platforms, send it to us by emailing [e-mail]. Please include the following details with your report:

• Description of the location and potential impact of the vulnerability;

• A detailed description of the steps required to reproduce the vulnerability

Scope

Any vulnerability not previously disclosed by us or our independent auditors in their reports

Guidelines

We require that all reporters:

• Make every effort to avoid privacy violations, degradation of user experience, disruption to production systems, and destruction of data during security testing

• Use the identified communication channels to report vulnerability information to us

• Keep information about any vulnerabilities you’ve discovered confidential between yourself and dYdX until we’ve had 30 days to resolve the issue

If you follow these guidelines when reporting an issue to us, we commit to:

• Not pursue or support any legal action related to your findings

• Work with you to understand and resolve the issue quickly (including an initial confirmation of your report within 72 hours of submission)

• Grant a monetary reward based on the OWASP risk assessment methodology

Development

Compile Contracts

Requires a running docker engine.

npm run build

Compile TypeScript

npm run build:js

Test

Requires a running docker engine.

Start test node:

docker-compose up

Deploy contracts to test node & run tests:

npm test

Just run tests (contracts must already be deployed to test node):

npm run test_only

Just deploy contracts to test node:

npm run deploy_test

Maintainers

• Brendan Chou @brendanchou [e-mail]

• Antonio Juliano @antoniojuliano [e-mail]

License

Apache-2.0