Maker Protocol Technical Docs
  • MakerDAO Technical Docs
  • Getting Started
    • Maker Protocol 101
  • Smart Contract Modules
    • Dai Module
      • Dai - Detailed Documentation
    • Core Module
      • Vat - Detailed Documentation
      • Spot - Detailed Documentation
    • Collateral Module
      • Join - Detailed Documentation
    • Liquidation 2.0 Module
    • System Stabilizer Module
      • Flapper - Detailed Documentation
      • Flopper - Detailed Documentation
      • Vow - Detailed Documentation
    • Oracle Module
      • Oracle Security Module (OSM) - Detailed Documentation
      • Median - Detailed Documentation
    • MKR Module
    • Governance Module
      • Spell - Detailed Documentation
      • Pause - Detailed Documentation
      • Chief - Detailed Documentation
    • Rates Module
      • Pot - Detailed Documentation
      • Jug - Detailed Documentation
    • Proxy Module
      • Proxy Actions - Detailed Documentation
      • Vote Proxy - Detailed Documentation
      • CDP Manager - Detailed Documentation
      • DSR Manager - Detailed Documentation
    • Flash Mint Module
    • Maker Protocol Emergency Shutdown
      • Emergency Shutdown for Partners
      • The Emergency Shutdown Process for Multi-Collateral Dai (MCD)
      • End - Detailed Documentation
      • ESM - Detailed Documentation
  • Glossary
    • MCD Glossaries
    • Smart Contract Annotations
  • Deployment Addresses
    • Maker Protocol Deployments
  • Security
    • Security for the Maker Protocol
  • Building on top of the Maker Protocol
    • Developer Guides and Tutorials
    • The Dai Javascript Library of the Maker Protocol
      • Getting started
      • Configuration
        • Plugins
      • Vault manager
      • Collateral types
      • Dai Savings Rate
      • Currency units
      • System data
      • Advanced
        • Transaction manager
        • DSProxy
        • Events
        • Using multiple accounts
        • Adding a new service
      • Single-Collateral Sai
        • Collateralized Debt Position
        • CDP Service
        • Price Service
        • System Status
        • Tokens
        • Token Conversion
        • Exchange Service
    • Pymaker
  • Keepers
    • The Auctions of the Maker Protocol
    • Auction Keepers
      • Auction Keeper Bot Setup Guide
    • Market Maker Keepers
      • Market Maker Keeper Bot Setup Guide
    • Cage Keeper
    • Simple Arbitrage Keeper
    • Chief Keeper
  • Command-line Interfaces
    • Seth
    • Multi Collateral Dai (MCD) CLI
    • Dai and Collateral Redemption during Emergency Shutdown
    • Emergency Shutdown (ES) CLI
  • Miscellaneous
    • Liquidations 1.2 System (Deprecated)
      • Cat - Detailed Documentation
      • Flipper - Detailed Documentation
    • SCD <> MCD Migration
    • Upgrading to Multi-Collateral Dai Guide
Powered by GitBook
On this page
  • Introduction
  • Using Hypothesis
  • Example
  • Usage
  • Our Hypothesis Groups:
  • Create a Hypothesis account here to get started!
Export as PDF
  1. Glossary

Smart Contract Annotations

In-line comments on the Maker Protocol's Core Smart Contracts

Introduction

Understanding the various terms used in our smart contracts can involve a significant time investment for developers looking at the codebase for the first time. Due to this fact, we need resources in various formats to ensure they can get up and running quickly. We believe, in order to complement the technical documentation on docs.makerdao.com, that highlighting sections of the codebase and annotating it with comments can surface relevant information developers need while reading the raw contracts in order to understand the contracts better.

Examples of how annotations may be useful for developers:

  • Highlight terms to display their definitions

    • Ex: ink, art

  • Explain various input parameters in-depth

    • Ex: Explain the precise role of users defined as gal or guy within input parameters.

  • Link to sections of other smart contracts from where function calls typically originate from

    • Ex: heal in Vat is called from Vow

  • Additional context to Maker specific design practices that other smart contract developers might not be accustomed to

    • Ex: Show the event log signature produced by the note modifier on a function.

  • Help developers navigate through scenarios that result in calls across multiple smart contracts

    • Ex: Keepers participating in collateral auctions kick the process with bite on Cat, bad debt is settled in Vat, accounted for in Vow, and a series of transactions on flip until they receive collateral they purchased for a discount.

  • Superimposing the operational view of the system on all functions will help developers build richer mental models of the Maker Protocol.

    • Ex: Annotating a function's auth modifier and mentioning the smart contracts authorized to call it.

Annotations will also serve as an open and collaborative discussion layer that helps developers discuss and evolve their understanding of the smart contracts over time.

Using Hypothesis

Example

Usage

Hypothesis annotations can be viewed by expanding a sidebar on the top right corner of your browser window.

There are three options to view annotations on a webpage:

Our Hypothesis Groups:

  • Public MakerDAO group that is open for everyone to both read and contribute.

PreviousMCD GlossariesNextMaker Protocol Deployments

Last updated 5 years ago

is a web-based tool that we use to annotate the codebase hosted on our Github org.

Check out the annotations of the Vat smart contract

Install the from the web store.

Follow instructions to setup a

Append to a URL.

MakerDAO restricted group- everyone is allowed to read annotations but only approved members can contribute .

Create a Hypothesis account to get started!

Hypothesis
here.
chrome extension
bookmarklet
https://via.hypothes.is
here
here