7. Security Best Practices
In this document, we describe best practices for interacting with Devise smart contracts and accessing the Devise alternative exchange from a security perspective.
Table of Contents
As a client, you use your Ethereum account credentials to interact with our smart contracts and access our data. It is paramount that you keep your Ethereum account credentials safe, preferably in a hardware wallet such as Ledger Nano S, and at the very least in a password-protected keystore file.
There are basically two types of accounts used in interactions with Devise: money accounts and API accounts.
A money account should be used for operations changing the state of the Ethereum blockchain, such as buying tokens, provisioning escrow accounts, placing bids, withdrawing tokens from escrow accounts, etc. These on-chain operations require gas, and therefore a money account needs to be sufficiently funded, at least in ether.
A money account has an ether (and potentially a Devise token) balance on it. It has real monetary value, and it should be treated with extra care. Losing it or having it compromised can cause you real monetary damage.
An API account, on the other hand, should only be used to authenticate API requests and does not need to hold any token, ether or Devise. Any Ethereum address can be designated as your beneficiary by calling DeviseClient.designate_beneficiary.
Since an API account does not need to keep an ether balance, it can be used in a systematic trading setting, for example, in a server process to automatically download latest weights everyday.
If you believe your API account has been compromised, you should designate a new beneficiary as soon as possible by making another call to DeviseClient.designate_beneficiary from the paying account.
In the devise Python package, all functions decorated with @costs_gas are transactions that cost ethers (gas) to call.
Here is an example:
The safest place to create/store your money account is in a hardware wallet. By doing so, you ensure that all signing operations will be done from within the pin-protected hardware itself, and your credentials will never be shared with any code requesting signing on your behalf, geniunely or not.
We officially support the Ledger Nano S hardware wallet, and plan to add support for the Trezor hardware wallet in the future.
The best practices for using hardware wallets are as follows:
- Only connect your hardware wallet to the USB port when you need to sign a transaction, and unplug it immediately after the signing operation is completed;
- Keep it offline at all other times.
When using a hardware wallet, it is very important to follow the security best practices of the manufacturer [1], especially guidelines around backing-up your mnemonic/passphrase. Failing to do so, could result in your tokens being stolen, which would be irreversible.
Your hardware wallet does not need to be plugged in at all times. It should only be connected to a USB port on your computer in order to either create a DeviseClient object using a hardware wallet as auth_type
from devise import DeviseClient
# Create a Devise client object to interact with our smart contracts.
devise_client = DeviseClient(account='0xd4a6B94E45B8c0185...', auth_type='ledger')or to execute functions that modify the state of the Ethereum blockchain (i.e. functions decorated with @cost_gas), for instance
# Provision your escrow account with DVZ by transferring qty ETH from your Ethereum wallet to the rental Smart contract.
qty = 1000
devise_client.fund_account(amount=qty, unit='ETH', source='ETH')Once the DeviseClient instance has been created, and/or the on-chain function has been executed, we advise you to unplug your hardware wallet right away.
The Ethereum foundation provides an official application, Ethereum Wallet, for creating Ethereum accounts with cryptographic credentials stored in password-protected keystore files.
If you would like to use this software wallet or other encrypted keystore files to generate your money account, it is very important to keep your password safe. Anyone who has access to your password and encrypted keystore files has full control of your accounts, and therefore unrestricted access to your Devise tokens and ethers.
While the devise Python package supports plaintext private keys, we strongly emphasize that you need to fully understand the security implications of using a DeviseClient instance with plaintext private keys before doing so.
To interact with our API, for instance, to retrieve latest portfolio weights updates so as to buy/sell leptons, or to request historical data, your requests need to be authenticated. This authentication uses secp256k1 ECDSA (Elliptic-Curve Digital Signature Algorithm) to verify that the issuer of the request is a legitimate beneficiary of requested data. To authenticate API calls, we support all methods previously discussed, except for hardware wallets, so as to impose a clear distinction between API accounts and money accounts.
The devise Python package provides convenient utility functions (e.g. DeviseClient.download_latest_weights, DeviseClient.download_historical_weights, DeviseClient.download_historical_returns) to download data from our API without implementing signing requests yourself. As long as a hardware wallet is not used as auth_type parameter when creating the DeviseClient instance corresponding to the API account, everything should just work.
If needed, an API account can be created automatically for you, and simultaneously designated as your beneficiary using the function DeviseClient.create_beneficiary. This function will log the path to your encrypted keystore file, and return the beneficiary's address.
Using the devise Python package to inspect the states of smart contracts, for example to retrieve your Devise token balance, does not require any signing medium.
We separated the money account role from the API account role so that your digital assets would be safe, as you don't have to use your money account as often. The Devise alternative exchange is the Devise community's asset, and we kindly ask that you keep it safe by protecting the credentials of your API account.
Devise data and/or account credentials should not be shared or sold.
We reserve the right to put in place measures to deter, identify and ban addresses suspected of sharing or selling Devise data or credentials. Once more, if you believe your API account has been compromised, you should designate a new beneficiary as soon as possible by calling DeviseClient.designate_beneficiary or DeviseClient.create_beneficiary from the paying account.