{"size": 9048, "ext": "scrbl", "max_stars_repo_path": "docs/scrbl/ref-networks.scrbl", "max_stars_repo_name": "wildework/reach-lang", "max_stars_repo_stars_event_min_datetime": null, "max_stars_repo_stars_event_max_datetime": null, "max_issues_repo_path": "docs/scrbl/ref-networks.scrbl", "max_issues_repo_name": "wildework/reach-lang", "max_issues_repo_issues_event_min_datetime": null, "max_issues_repo_issues_event_max_datetime": null, "max_forks_repo_path": "docs/scrbl/ref-networks.scrbl", "max_forks_repo_name": "wildework/reach-lang", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": null, "max_issues_count": null, "max_forks_count": null, "avg_line_length": 48.6451612903, "max_line_length": 366, "alphanum_fraction": 0.7757515473}
#lang scribble/manual
@(require "lib.rkt")

@title[#:version reach-vers #:tag "ref-networks" #:style
'toc]{Consensus Network Connectors}

This section describes the @tech{consensus network} @tech{connectors}
supported by Reach version @|reach-vers|.

@local-table-of-contents[#:style 'immediate-only]

@section[#:tag "ref-network-algo"]{Algorand}

The @link["https://www.algorand.com/"]{Algorand} Reach @tech{connector} generates a set of
@tech{contracts} that manage one instance of the @|DApp|'s
execution.

It uses finite on-chain state.
The @|DApp| consists of one application and one contract-controlled escrow account.

It relies on versions of @tt{algod} that support TEAL version 4, such as Algorand 2.7.1 from July 2021.
It uses the Algorand @tt{indexer} version 2 to lookup and monitor @tech{publications}; in other words, it does @emph{not} rely on any communication network other than Algorand itself.

Algorand uses the SHA256 algorithm to perform @tech{digest}s.
Its @tech{bit width} is 64-bits.

@tech{Non-network tokens} are compiled to @link["https://developer.algorand.org/docs/features/asa/"]{Algorand Standard Assets} (ASAs).
Specifically, the @reachin{Token} type refers to the id of the ASA.

@tech{Token minting} creates an ASA owned and managed by the contract account.
Freezing, clawback, reserves, and separate managers are not supported.

@tech{Views} are compiled to client-side functions that can interpret the global and local state of the Algorand Application associated with the @|DApp|.
This means they are sensitive to the particular compilation details of the particular Reach program.
We hope to work with the Algorand community to define a standard for @tech{views}.
@tech{Views} expand the on-chain state to include the free variables of all values bound to a @tech{view}.

@tech{Linear state} is compiled into Application Local State.
This means that participants must explicitly "opt-in" to storing this state on their account (which increases their minimum balance).
The Reach standard library will do this automatically when connecting to Reach generated contracts, but other users must be specifically programmed to do this.
This "opt-in" requirement means that @|DApps| with @tech{linear state} deployed on Algorand can deadlock and be held hostage:
Suppose that Alice transfers 10 ALGO to a contract in step one, then in step two, the consensus must store a value associated with Bob, and then she can receive her 10 ALGO back, then the program terminates.
On some networks, Alice can perform these two steps completely on her own and she is in complete control of her funds.
However, on Algorand, running this program requires that Bob "opt-in" to storing values for the application.
We hope that future versions of Algorand will allow other parties to pay the fees to "opt-in" to applications to prevent these kinds of deadlock attacks.

In Algorand, @tech{network time} corresponds to round numbers and @tech{network seconds} correspond to the Unix timestamp of the previous round.
(This is because the current round's timestamp is not determined until after it is finalized.
This means that a @tech{network second}-based deadline could be exceeded by the round time of the network, which is typically five seconds.)

The connector provides a binding named @reachin{ALGO} to
@tech{backends}.

@tech{Backends} must respect the following environment variables:

@itemlist[

@item{@defenv{ALGO_TOKEN} is used as the API token for your @tt{algod}.}
@item{@defenv{ALGO_SERVER} is used as the address of your @tt{algod}.}
@item{@defenv{ALGO_PORT} is used as the port of your @tt{algod}.}

@item{@defenv{ALGO_INDEXER_TOKEN} is used as the API token for your @tt{indexer}.}
@item{@defenv{ALGO_INDEXER_SERVER} is used as the address of your @tt{indexer}.}
@item{@defenv{ALGO_INDEXER_PORT} is used as the port of your @tt{indexer}.}

@item{@defenv{ALGO_FAUCET_PASSPHRASE} is used as the mnemonic for the faucet of your network.
This is useful if you are running your own testing network.}

]

@section[#:tag "ref-network-cfx"]{Conflux}

The @link["https://confluxnetwork.org/"]{Conflux} Reach @tech{connector} works almost identically to the @seclink["ref-network-eth"]{Ethereum connector}, except that it behaves differently at runtime: using, for example, @link["https://portal.confluxnetwork.org/"]{Conflux Portal} rather than @link["https://metamask.io/"]{MetaMask}, and connecting to Conflux nodes.

@tech{Backends} must respect the following environment variables:

@itemlist[

@item{@defenv{CFX_NODE_URI} is used to contact the Conflux node.
It defaults to @litchar{http://localhost:12537}.}

@item{@defenv{CFX_NETWORK_ID} is used to determine the Conflux network id.
It defaults to @litchar{999}.}

]

@subsection[#:tag "cfx-faq"]{FAQ}

@subsubsection[#:tag "cfx-faq-mainnet"]{How do I run my Reach DApp on CFX TestNet or MainNet?}

You can add the following JavaScript near the beginning of your index.js or index.mjs file
in order to run on Conflux TestNet:

@js{
reach.setProviderByName('TestNet');
}

Or this to run on Conflux MainNet:

@js{
reach.setProviderByName('MainNet');
}

It is strongly recommended that you also use @jsin{setQueryLowerBound}
to avoid waiting for unnecessary queries.
For example, this code snippet sets the lower bound at 2000 blocks ago:

@js{
const now = await reach.getNetworkTime();
reach.setQueryLowerBound(reach.sub(now, 2000));
}

@subsubsection[#:tag "cfx-faq-query"]{Why is DApp startup very slow? Why do I need to use @tt{setQueryLowerBound}?}

DApp startup doesn't have to be slow.
Reach relies on querying Conflux event logs in order to run the DApp.
The Conflux network does not yet provide fast APIs for querying event logs for a given contract across all time,
so instead, Reach incrementally queries across chunks of 1000 blocks at a time.
You can use @jsin{setQueryLowerBound} to help Reach know at what block number to start querying,
so that it does not have to start querying at the beginning of time, which can take quite a while.

@subsubsection[#:tag "cfx-faq-cplocal"]{How can I use ConfluxPortal with the Reach devnet?}

If you find that ConfluxPortal's Localhost 12537 default configuration does not work correctly with Reach apps,
you can try configuring ConfluxPortal to use a custom RPC endpoint:

@itemlist[
  @item{Click the network dropdown in Conflux Portal}
  @item{Select: Custom RPC}
  @item{Use RPC url: http://127.0.0.1:12537}
]

If your locally-running Conflux devnet restarts,
you may find that you need to reset ConfluxPortal's account history,
which you can do like so:

@itemlist[
  @item{Select the desired account}
  @item{Click the profile image of the account (top-right)}
  @item{Click Settings > Advanced > Reset Account > (confirm) Reset}
  @item{Switch to a different network and back}
  @item{CTRL+SHIFT+R to hard-reset the webpage.}
]

@section[#:tag "ref-network-eth"]{Ethereum}

The @link["https://ethereum.org/"]{Ethereum} Reach @tech{connector} generates a @tech{contract} that
manages one instance of the @|DApp|'s execution.
It is guaranteed to
use exactly one word of on-chain state, while each piece of @tech{consensus state} appears as a transaction argument.

Ethereum uses the Keccak256 algorithm to perform @tech{digest}s.
Its @tech{bit width} is 256-bits.

@tech{Non-network tokens} are compiled to @link["https://ethereum.org/en/developers/docs/standards/tokens/erc-20/"]{ERC-20} fungible tokens.
Specifically, the @reachin{Token} type refers to the address of the ERC-20 contract.
@tech{Token minting} launches a fresh ERC-20 contract based on the OpenZeppelin ERC-20 implementation, which stores additional metadata and allows the creator to burn tokens and destroy the token if there is no supply (i.e. it has all been burned).

@tech{Views} are compiled to @litchar{view} functions.
A @tech{view} named @litchar{X.Y} will be named @litchar{X_Y}.
@tech{Views} expand the on-chain state to include the free variables of all values bound to a @tech{view}.

In Ethereum, @tech{network time} corresponds to block numbers and @tech{network seconds} correspond to the Unix timestamp of the block.

The connector provides a binding named @reachin{ETH} to
@tech{backends}.

During compilation, the connector produces one intermediate output: @filepath{input.export.sol}, containing
the Solidity code implementing the @tech{contract}.

A few details of Ethereum leak through to Reach.
The node that a given @tech{participant} is connected to does not instantly know that its blocks are correct and may revert past transactions after it reaches consensus with the rest of the network.
This means that Reach applications must not make externally observable effects until after such consensus is reached.

@tech{Backends} must respect the following environment variables:

@itemlist[

@item{@defenv{ETH_NODE_URI} is used to contact the Ethereum node.
It defaults to @litchar{http://localhost:8545}.}

@item{@defenv{ETH_NODE_NETWORK} is used to name the Ethereum network.
It defaults to @litchar{unspecified}.}

]
