Synthetix v3

Package	Coverage
@synthetixio/core-utils
@synthetixio/core-contracts
@synthetixio/core-modules
@synthetixio/router
@synthetixio/main

Documentation

Please refer to the Official Documentation for high level concepts of the Synthetix v3 protocol, as well as auto generated docs from natspec.

Package structure

This is a monorepo with the following folder structure and packages:

.
├── markets                      // Standalone projects that extend the core Synthetix protocol with markets.
│   ├── legacy-market            // Market that connects Synthetix's v2 and v3 versions.
│   └── spot-market              // Market extension for spot synths.
│
├── protocol                     // Core Synthetix protocol projects.
│   ├── oracle-manager           // Composable oracle and price provider for teh core protocol.
│   └── synthetix                // Core protocol (to be extended by markets).
│
└── utils                        // Utilities, plugins, tooling.
    ├── common-config            // Common npm and hardhat configuration for multiple packages in the monorepo.
    ├── core-contracts           // Standard contract implementations like ERC20, adapted for custom router storage.
    ├── core-modules             // Modules intended to be reused between multiple router based projects.
    ├── core-utils               // Simple Javascript/Typescript utilities that are used in other packages (e.g. test utils, etc).
    ├── router                   // Cannon plugin that merges multiple modules into a router contract.
    ├── hardhat-storage          // Hardhat plugin used to detect storage collisions between proxy implementations.
    ├── sample-project           // Sample project based on router proxy and cannon.
    └── solhint-plugin-numcast   // Solidity linter plugin to avoid low level numeric casts which can lead to silent overflows.

Router Proxy

All projects in this monorepo that involve contracts use a proxy architecture developed by Synthetix referred to as the "Router Proxy". It is basically a way to merge several contracts, which we call "modules", into a single implementation contract which is the router itself. This router is used as the implementation of the main proxy of the system.

See the Router README for more details.

⚠️ When using the Router as an implementation of a UUPS Universal Upgradeable Proxy Standard be aware that any of the public functions defined in the Proxy could clash and override any of the Router modules functions. A malicious proxy owner could use this type of obfuscation to have users run code which they do not want to run. You can imagine scenarios where the function names do not look similar but share a function selector. ⚠️

Information for Developers

If you intend to develop in this repository, please read the following items.

Installation Requirements

• Foundry
• NPM version 8
• Node version 16

Console logs in contracts

In the contracts, use import "hardhat/console.sol";, then run DEBUG=cannon:cli:rpc npm test.

Deployment Guide

Deployment of the protocol is managed in the synthetix-deployments repository.

To prepare for system upgrades, this repository is used to release new versions of the protocol and markets.

Preparing a Release

• Ensure you have the latest version of Cannon installed: npm i -g @usecannon/cli and hardhat-cannon is upgraded to the latest through the repository.
• After installing for the first time, run cannon setup to configure IPFS and a reliable RPC endpoint to communicate with the Cannon package registry.
• Run npm i and npm run build in the root directory of the repository.
• From the directory of the package you're releasing, run npx hardhat cannon:build.
  • If you're upgrading the synthetix package, also run npm run build && npx hardhat cannon:build cannonfile.test.toml to generate the testable package.
• Confirm the private key that owns the corresponding namespace in the package registry is set in the .env file as DEPLOYER_PRIVATE_KEY.
• Publish the release to Cannon package registry with npx hardhat cannon:publish --network mainnet.
• Increment the version in the relevant package.json files. The repositories should always contain the version number of the next release.
  • If you've upgraded synthetix, also increment the version of the package.json file in the root directory. Also upgrade the version in markets/spot-market/cannonfile.toml and markets/spot-market/cannonfile.test.toml.
  • If you've upgraded the oracle manager, bump the version of the oracle manager in protocol/synthetix/cannonfile.toml and protocol/synthetix/cannonfile.test.toml.
• Run npm i in the root directory.
• Commit and push the change to this repository.

Then, follow the instructions in the synthetix-deployments repository.

Finalizing a Release

After the new version of the synthetix-omnibus package has been published, the previously published packages can be verified on Etherscan.

From the relevant package's directory, run the following command for each network it was deployed on: npx hardhat cannon:verify <PACKAGE_NAME>:<VERSION> --network <NETWORK_NAME>