index.html

<!DOCTYPE HTML>
<html lang="en" class="light" dir="ltr">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>Introduction - snops</title>


        <!-- Custom HTML head -->
        
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff">

        <link rel="icon" href="favicon.svg">
        <link rel="shortcut icon" href="favicon.png">
        <link rel="stylesheet" href="css/variables.css">
        <link rel="stylesheet" href="css/general.css">
        <link rel="stylesheet" href="css/chrome.css">
        <link rel="stylesheet" href="css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
        <link rel="stylesheet" href="fonts/fonts.css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="highlight.css">
        <link rel="stylesheet" href="tomorrow-night.css">
        <link rel="stylesheet" href="ayu-highlight.css">

        <!-- Custom theme stylesheets -->

    </head>
    <body class="sidebar-visible no-js">
    <div id="body-container">
        <!-- Provide site root to javascript -->
        <script>
            var path_to_root = "";
            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
        </script>

        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script>
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script>
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
            if (theme === null || theme === undefined) { theme = default_theme; }
            var html = document.querySelector('html');
            html.classList.remove('light')
            html.classList.add(theme);
            var body = document.querySelector('body');
            body.classList.remove('no-js')
            body.classList.add('js');
        </script>

        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

        <!-- Hide / unhide sidebar before it is displayed -->
        <script>
            var body = document.querySelector('body');
            var sidebar = null;
            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            } else {
                sidebar = 'hidden';
            }
            sidebar_toggle.checked = sidebar === 'visible';
            body.classList.remove('sidebar-visible');
            body.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <div class="sidebar-scrollbox">
                <ol class="chapter"><li class="chapter-item expanded affix "><a href="../index.html" class="active">Introduction</a></li><li class="chapter-item expanded affix "><li class="spacer"></li><li class="chapter-item expanded affix "><li class="part-title">Architecture</li><li class="chapter-item expanded "><a href="architecture/index.html"><strong aria-hidden="true">1.</strong> Overview</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="architecture/CONTROL_PLANE.html"><strong aria-hidden="true">1.1.</strong> Control Plane</a></li><li class="chapter-item expanded "><a href="architecture/AGENTS.html"><strong aria-hidden="true">1.2.</strong> Agents</a></li><li class="chapter-item expanded "><a href="architecture/RUNNERS.html"><strong aria-hidden="true">1.3.</strong> Runners</a></li></ol></li><li class="chapter-item expanded "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="user_guide/index.html"><strong aria-hidden="true">2.</strong> Overview</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="user_guide/envs/index.html"><strong aria-hidden="true">2.1.</strong> Setting up Environments</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="user_guide/envs/STORAGE.html"><strong aria-hidden="true">2.1.1.</strong> Storage</a></li><li class="chapter-item expanded "><a href="user_guide/envs/TOPOLOGY.html"><strong aria-hidden="true">2.1.2.</strong> Topology</a></li><li class="chapter-item expanded "><a href="user_guide/envs/CANNONS.html"><strong aria-hidden="true">2.1.3.</strong> Cannons</a></li></ol></li><li class="chapter-item expanded "><a href="user_guide/running/index.html"><strong aria-hidden="true">2.2.</strong> Running</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="user_guide/running/AGENT.html"><strong aria-hidden="true">2.2.1.</strong> Agent</a></li><li class="chapter-item expanded "><a href="user_guide/running/CONTROL_PLANE.html"><strong aria-hidden="true">2.2.2.</strong> Control Plane</a></li><li class="chapter-item expanded "><a href="user_guide/running/METRICS_AND_LOGGING.html"><strong aria-hidden="true">2.2.3.</strong> Metrics and Logging</a></li></ol></li><li class="chapter-item expanded "><a href="user_guide/clis/index.html"><strong aria-hidden="true">2.3.</strong> CLI Help</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="user_guide/clis/SNARKOS_AOT.html"><strong aria-hidden="true">2.3.1.</strong> AOT</a></li><li class="chapter-item expanded "><a href="user_guide/clis/SNOPS_AGENT.html"><strong aria-hidden="true">2.3.2.</strong> AGENT</a></li><li class="chapter-item expanded "><a href="user_guide/clis/SNOPS.html"><strong aria-hidden="true">2.3.3.</strong> SNOPS</a></li><li class="chapter-item expanded "><a href="user_guide/clis/SNOPS_CLI.html"><strong aria-hidden="true">2.3.4.</strong> SNOPS_CLI</a></li></ol></li></ol></li><li class="chapter-item expanded "><li class="part-title">Developing</li><li class="chapter-item expanded "><a href="developing/index.html"><strong aria-hidden="true">3.</strong> Developing</a></li><li class="chapter-item expanded affix "><li class="spacer"></li><li class="chapter-item expanded affix "><li class="part-title">Glossary</li><li class="chapter-item expanded "><a href="glossary/index.html"><strong aria-hidden="true">4.</strong> Overview</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="glossary/ACTIONS.html"><strong aria-hidden="true">4.1.</strong> Actions</a></li><li class="chapter-item expanded "><a href="glossary/IDs.html"><strong aria-hidden="true">4.2.</strong> IDs</a></li><li class="chapter-item expanded "><a href="glossary/NODE_TARGETS.html"><strong aria-hidden="true">4.3.</strong> Node Targets</a></li><li class="chapter-item expanded "><a href="glossary/RETENTION_RULES.html"><strong aria-hidden="true">4.4.</strong> Retention Rules</a></li></ol></li></ol>
            </div>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                <div class="sidebar-resize-indicator"></div>
            </div>
        </nav>

        <!-- Track and set sidebar scroll position -->
        <script>
            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
            sidebarScrollbox.addEventListener('click', function(e) {
                if (e.target.tagName === 'A') {
                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
                }
            }, { passive: true });
            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
            sessionStorage.removeItem('sidebar-scroll');
            if (sidebarScrollTop) {
                // preserve sidebar scroll position when navigating via links within sidebar
                sidebarScrollbox.scrollTop = sidebarScrollTop;
            } else {
                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
                var activeSection = document.querySelector('#sidebar .active');
                if (activeSection) {
                    activeSection.scrollIntoView({ block: 'center' });
                }
            }
        </script>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                                <div id="menu-bar-hover-placeholder"></div>
                <div id="menu-bar" class="menu-bar sticky">
                    <div class="left-buttons">
                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                            <i class="fa fa-bars"></i>
                        </label>
                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                            <i class="fa fa-paint-brush"></i>
                        </button>
                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                        </ul>
                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                            <i class="fa fa-search"></i>
                        </button>
                    </div>

                    <h1 class="menu-title">snops</h1>

                    <div class="right-buttons">
                        <a href="print.html" title="Print this book" aria-label="Print this book">
                            <i id="print-button" class="fa fa-print"></i>
                        </a>

                    </div>
                </div>

                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script>
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <!-- TODO snops image <p align="center">
  <a href="https://monadic.us/">
    <img width="90%" alt="snops" src="">
  </a>
</p> -->
<h1 align="center">
  snarkOPs
</h1>
<p><a href="#snops-quickstart">Snops Quickstart</a> | <a href="#snarkos-aot-quickstart">snarkos-aot Quickstart</a></p>
<p>This repository is home to the <code>snops</code> (snarkOS operations) ecosystem, and
<code>snarkos-aot</code>, a crate for performing ahead-of-time ledger actions, transaction
authorizations, and various tools for helping with developing Aleo programs.</p>
<p>snops is a suite of tools that can be used to maintain <a href="https://aleo.org/">Aleo</a>
network environments. The environments are defined in a manner similar to
infrastructure-as-code, which means you can create repeatable infrastructure
using the environment schema.</p>
<p>This can be used to create devnets, simulate events on the network like outages
and attacks, and guarantee metrics.</p>
<p>To learn more about <code>snops</code> we recommend checking out the mdbook <a href="https://monadicus.github.io/snarkops/">here</a>.</p>
<h2 id="snops-quickstart"><a class="header" href="#snops-quickstart">Snops Quickstart</a></h2>
<h3 id="easy-setup"><a class="header" href="#easy-setup">Easy Setup</a></h3>
<p><code>snops</code> contains several components that can be compiled separately. The <code>release-big</code> build profile allows for faster near-release profile performance with faster near-debug profile build times.</p>
<ol>
<li>
<p>Install <a href="https://www.rust-lang.org/">rust</a></p>
</li>
<li>
<p>Clone the repo</p>
</li>
<li>
<p>Start + build the control plane: <code>./scripts/control_plane.sh</code></p>
<p>The controlplane is the webserver that communicates to agents how to
run snarkOS, or what transactions to execute.</p>
</li>
<li>
<p>In another terminal, install the cli: <code>cargo install --path ./crates/snops-cli</code>, or build with <code>cargo xtask build cli</code> and use from <code>target/release-big/snops-cli</code>.</p>
<p>The cli is used to interact with the controlplane and manage environments.
It provides JSON based output. We recommend pairing our cli with <a href="https://jqlang.github.io/jq/"><code>jq</code></a> when leveraging other scripts and tools</p>
</li>
<li>
<p>Build the agent: <code>cargo xtask build agent</code></p>
<p>The agent is a lightweight service that starts up <code>snarkos-aot</code> which
automatically configures snarkos nodes, or executes transactions.</p>
</li>
<li>
<p>Build <code>snarkos-aot</code> (for running nodes): <code>cargo xtask build aot</code></p>
<p><code>snarkos-aot</code> is an alternative snarkOS CLI providing more developer-oriented
features as well as tooling for distributed transaction generation and execution.</p>
</li>
<li>
<p>In separate terminals, start up some agents with the following commands:</p>
<pre><code class="language-sh">./script/agent.sh 0
./script/agent.sh 1
./script/agent.sh 2
./script/agent.sh 3
</code></pre>
<p>Each of these can be dynamically configured as snarkos nodes. The default
agent configuration should connect to a locally operated controlplane.</p>
</li>
</ol>
<h3 id="local-isolated-networks-isonets"><a class="header" href="#local-isolated-networks-isonets">Local Isolated Networks (Isonets)</a></h3>
<p>This example requires 4 agents and the control plane to be running. It allows you to run a devnet with a custom genesis block.</p>
<ol>
<li>Start the environment: <code>snops-cli env apply specs/test-4-validators.yaml</code></li>
<li>Check the current network height: <code>snops-cli env height</code></li>
<li>Look at the latest block: <code>snops-cli env block</code></li>
<li>Look at the genesis block: <code>snops-cli env block 0</code></li>
<li>Stop the environment: <code>snops-cli env delete</code></li>
</ol>
<h3 id="isonet-transfers"><a class="header" href="#isonet-transfers">Isonet Transfers</a></h3>
<p>Using the setup for a <a href="#local-isonets">Local Isonet</a>, executing Aleo programs has never
been more convenient. Snops aliases locally generated keys automatically from configuration and
reduces the need to keep track of individual key files.</p>
<ol>
<li>
<p>Start an environment (see previous example)</p>
</li>
<li>
<p>Start a compute agent: <code>./scripts/agent_compute.sh 0</code></p>
<p>Compute agents are able to distribute the execution of transactions,
offloading the compute task to different servers.</p>
</li>
<li>
<p>Check the balance of committee member 1's key:</p>
<pre><code class="language-sh">$ snops-cli env balance committee.1
10000000000000
</code></pre>
</li>
<li>
<p>Transfer 1 credit to committee member 1 from committee member 0 (look on snarkos this command would require MANY more flags):</p>
<pre><code class="language-sh">snops-cli env action execute transfer_public committee.1 1_000_000u64
</code></pre>
</li>
<li>
<p>Check the balance of committee member 1's key (it may take a few seconds for the block to advance):</p>
<pre><code class="language-sh">snops-cli env balance committee.1
10000001000000
</code></pre>
</li>
</ol>
<h3 id="isonet-program-deployments"><a class="header" href="#isonet-program-deployments">Isonet Program Deployments</a></h3>
<p>Deploying and executing Aleo programs on your isonets is easiest with snops. You do not need any extra json files or tooling, only a standalone <code>.aleo</code> file.</p>
<ol>
<li>
<p>Use the same setup as before</p>
</li>
<li>
<p>Create a file <code>mapping_example.aleo</code> with the following contents:</p>
<pre><code class="language-js">program mapping_example.aleo;

mapping mymapping:
  key as u8.public;
  value as u8.public;

function store:
    input r0 as u8.public;
    input r1 as u8.public;
    async store r0 r1 into r2;
    output r2 as mapping_example.aleo/store.future;

finalize store:
    input r0 as u8.public;
    input r1 as u8.public;
    set r1 into mymapping[r0];
</code></pre>
</li>
<li>
<p>Deploy the program: <code>snops-cli env action deploy ./mapping_example.aleo</code></p>
</li>
<li>
<p>Verify the program is on the chain: <code>snops-cli env program mapping_example.aleo</code></p>
</li>
<li>
<p>Check an example mapping</p>
<pre><code class="language-sh">$ snops-cli env mapping mapping_example.aleo mymapping 0u8
{
  "value": null
}
</code></pre>
</li>
<li>
<p>Execute the <code>store</code> function on-chain: <code>snops-cli env action execute mapping_example.aleo/store 0u8 5u8</code></p>
</li>
<li>
<p>Check the example mapping for its updated value</p>
<pre><code class="language-sh">$ snops-cli env mapping mapping_example.aleo mymapping 0u8
{
  "value": "5u8"
}
</code></pre>
</li>
</ol>
<h2 id="snarkos-aot-quickstart"><a class="header" href="#snarkos-aot-quickstart">SnarkOS-aot Quickstart</a></h2>
<p><code>snarkos-aot</code> provides various CLI tools to help with developing and executing
Aleo programs as well as interact with snarkOS ledgers.</p>
<p>Build <code>snarkos-aot</code> with: <code>cargo xtask build aot</code>.
The compiled binary can be found in <code>target/release-big/snarkos-aot</code>.</p>
<p>Use the <code>NETWORK</code> environment variable to specify <code>mainnet</code> (default),
<code>testnet</code>, or <code>canary</code>.</p>
<h3 id="transaction-authorizations"><a class="header" href="#transaction-authorizations">Transaction Authorizations</a></h3>
<p>Typically when executing snarkOS transactions you specify the program and inputs
and receive a proof. Behind the scenes, snarkVM is using a private key to
"authorize" the proof for the program execution, and "authorize" the proof for
the fee.</p>
<p>Creating authorizations is much quicker than executing the transaction, and the
process can be done airgapped or even on web clients.</p>
<pre><code class="language-sh"># Create an authorization for a executing transfer_public to the "example.aleo" program for 1 microcredit
NETWORK=testnet snarkos-aot auth program --private-key &lt;PK&gt; credits.aleo/transfer_public example.aleo 1u64 &gt; auth.json
# The same as above but with a different private key
NETWORK=testnet snarkos-aot auth program --private-key &lt;PK&gt; --fee-private-key &lt;PK&gt; credits.aleo/transfer_public example.aleo 1u64 &gt; auth.json

# Create an authorization for deploying a program (from my_program.aleo)
NETWORK=testnet snarkos-aot auth deploy --private-key &lt;PK&gt; my_program.aleo
# Determine the cost to deploy a program (from stdin)
cat my_program.aleo | NETWORK=testnet snarkos-aot auth deploy --private-key &lt;PK&gt; - | NETWORK=testnet snarkos-aot auth cost -

# Execute an authorization from auth.json without broadcasting it (the - means stdin)
cat auth.json | NETWORK=testnet snarkos-aot auth execute - --query https://api.explorer.aleo.org/v1

# Get the cost of an authorization (program or deployment) without executing the transaction
cat auth.json | NETWORK=testnet snarkos-aot auth cost -

# Derive the transaction id from an authorization without executing it
cat auth.json | NETWORK=testnet snarkos-aot auth id -

</code></pre>
<h3 id="program-helpers"><a class="header" href="#program-helpers">Program Helpers</a></h3>
<p><code>snarkos-aot</code> contains various tools to programmatically interact with aleo program.</p>
<p>If you don't have any Aleo programs you can download a program (<code>credits.aleo</code>)
from Aleo Explorer with the following commands. You can find a list of
programs on <a href="https://explorer.aleo.org/programs">Aleo Explorer's Programs List</a>.</p>
<pre><code class="language-sh">NETWORK=testnet
PROGRAM=credits.aleo
# Download a program, then un-jsonify it
curl https://api.explorer.aleo.org/v1/$NETWORK/program/$PROGRAM | jq -r &gt; $PROGRAM
</code></pre>
<p>Below are some <code>snarkos-aot</code> commands for interacting with programs.</p>
<pre><code class="language-sh"># Get a program's id from a text file
$ snarkos-aot program id ./credits.aleo
credits.aleo

# Calculate the cost of deploying a program
$ snarkos-aot program cost ./example.aleo
2568400

# Get a list of imports for a program (output in a json format with --json)
$ snarkos-aot program imports ./staking_v1.aleo --json
["credits.aleo"]

# Get a list of functions (and respective inputs/outputs) for a program (jq for formatting)
$ snarkos-aot program functions ./domainnames.aleo --json | jq
{
  "validate_name": {
    "inputs": [
      "[u128; 4u32].private"
    ],
    "outputs": [
      "boolean.private"
    ]
  }
}
</code></pre>
<h3 id="account-helpers"><a class="header" href="#account-helpers">Account Helpers</a></h3>
<p>Need to generate a bunch of vanity accounts for testing?</p>
<pre><code># Generate 5 accounts that have addresses that start with `aleo1f00`
snarkos-aot accounts 5 --vanity f00
</code></pre>
<h2 id="contributing"><a class="header" href="#contributing">Contributing</a></h2>
<p><code>snops</code> is free and open source. You can find the source code on
<a href="https://github.com/monadicus/snarkops">GitHub</a> and issues and feature requests can be posted on
the <a href="https://github.com/monadicus/snarkops/issues">GitHub issue tracker</a>. If you'd like to contribute, please read
the <a href="https://github.com/monadicus/snarkops/blob/main/CONTRIBUTING.md">CONTRIBUTING</a> guide and consider opening
a <a href="https://github.com/monadicus/snarkops/pulls">pull request</a>.</p>
<h2 id="license"><a class="header" href="#license">License</a></h2>
<p>The <code>snops</code> source and documentation are released under
the <a href="https://github.com/monadicus/snarkops/blob/main/LICENSE">MIT License
</a>.</p>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->

                            <a rel="next prefetch" href="architecture/index.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                <i class="fa fa-angle-right"></i>
                            </a>

                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">

                    <a rel="next prefetch" href="architecture/index.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                        <i class="fa fa-angle-right"></i>
                    </a>
            </nav>

        </div>


        <script>
            window.playground_copyable = true;
        </script>


        <script src="elasticlunr.min.js"></script>
        <script src="mark.min.js"></script>
        <script src="searcher.js"></script>

        <script src="clipboard.min.js"></script>
        <script src="highlight.js"></script>
        <script src="book.js"></script>

        <!-- Custom JS scripts -->


    </div>
    </body>
</html>