Orchid Network Protocol

1 Summary

ConsenSys Diligence conducted a security audit on Orchid Labs’ network protocol, more specifically, the Ethereum smart contracts that are part of the bigger network protocol codebase.

Orchid Labs was founded with a mission to create a more open and more accessible internet. As part of this quest they created the Orchid network protocol, a truly decentralized VPN service.

The way the Orchid network achieves true decentralization is by allowing anyone to join the network as a bandwidth provider and anyone to use the service as an end user. This permissionless environment is achievable with the usage of programmatic, probabilistic micropayments on top of Ethereum, the focus of this audit.

2 Audit Scope

This audit covered the following files:

The audit activities can be grouped into the following three broad categories:

1. Security: Identifying security related issues within the contract.
2. Architecture: Evaluating the system architecture through the lens of established smart contract best practices.
3. Code quality: A full review of the contract source code. The primary areas of focus include:
   • Correctness
   • Readability
   • Scalability
   • Code complexity
   • Quality of test coverage

3 System Overview

Orchid network is comprised of two main on-chain components, OrchidDirectory and OrchidLottery. They both play important roles in setting up the proper incentives for the correct functioning of the bandwidth market of the VPN product.

OrchidDirectory keeps track of staked OXT tokens (Orchid’s native token). The staked amounts are held in a binary tree that allows for easy weighted random selection by clients. Clients then purchase bandwidth from the selected stakee.

OrchidLottery is an implementation of probabilistic micropayments. These are used to stream payments to bandwidth providers.

These two components are completely independent of each other and meant to be used for the VPN client in different stages of the product usage.

A rough outline of the usage flow pertaining to these on-chain components is as follows:

1. The VPN client starts by engaging with an Ethereum client that runs the selection routine for the nodes by running code present in OrchidDirectory. This step can remain fully trustless by asking the Ethereum client (which may be untrusted) for merkle proofs of the selected storage blocks (and the blocks themselves). This effectively makes OrchidDirectory.scan(), which performs the random weighted selection, more of a reference implementation than a fundamental part of the staking infrastructure.
2. After the traffic route is set up, clients need to be able to pay for packets of data as they’re being forwarded. This requires a payment system that enables low-cost micropayments. This is made possible (i.e., trustlessly enforced) by the OrchidLottery smart contract, a probabilistic micropayments implementation. OrchidLottery holds the end user’s funds that are meant to be disbursed to bandwidth providers, as well as an escrow amount to be burned as a penalty in the case of insufficient available payment funds.

A probabilistic micropayment is a message, signed by the payer, that behaves very much like a lottery ticket. It entitles the recipient of the message to a possible payment of a certain amount with a given probability. This payment is enforced on-chain. Although each payment is probabilistic, over a large number of such payments, the actual amount paid trends towards the expected value.

Creating these probabilistic micropayments is done offline and is computationally inexpensive, so it can be used to pay for a continuous stream of packets without disruption or the need to wait for on-chain confirmations.

4 Key Observations/Recommendations

• The usage of the Ethereum blockchain within the Orchid network protocol is an exceptional example of decentralized coordination with on-chain enforcement. 👏
• The formal modeling of Orchid’s network market in the presented whitepaper is impressively thorough and shows the amount of consideration and thought that went into the product planning.
• The code lacks detailed documentation. The whitepaper explains the algorithms at a high level, but there is no documentation that explains the code itself. A good start would be clear variable and function names as well as explanatory code comments.
• A good test suite enables the early suppression of bugs and protection against future bugs introduced by composability, i.e., adding new features to the code that breaks some security assumption of a previously written section. The codebase is lacking in tests.
• Good code coverage helps immensely to catch control flow errors. While high code coverage gives no guarantees of algorithmic correctness, a lack of coverage usually allows for control flow bugs to exist. Two issues found during the audit would have been discovered during development by measuring code coverage. The Diligence team recommends integrating a code coverage tool and achieving 100% code coverage.

5 Security Specification

This section describes, from a security perspective, the expected behavior of the system under audit. It is not a substitute for documentation. The purpose of this section is to identify specific security properties that were validated by the audit team.

5.1 Actors

The relevant actors are as follows:

• VPN users – Users find providers via the directory and purchase bandwidth from those providers via micropayments.
• Bandwidth providers – Providers are advertised in the directory and sell bandwidth via micropayments.
• Stakers – To mitigate certain kinds of attacks, the VPN software prefers bandwidth providers with more Orchid tokens (OXT) at stake. Stakers stake their tokens to increase the likelihood that a given bandwidth provider will be selected.
• Micropayment funders – Anyone can establish a fund for micropayments.
• Micropayment signers – Signers authorize micropayments. There are potentially many signers for a given fund.
• Orchid – Orchid itself deploys the smart contracts but retains no special privileges.

5.2 Trust Model

In any smart contract system, it’s important to identify what trust is expected/required between various actors.

• None of the participants need to trust Orchid because Orchid retains no special privileges after contract deployment.
• A micropayment funder authorizes certain signers to act on their behalf, and those signers must be trusted by the funder to spend up to the total amount in the fund.
• Users and bandwidth providers need to trust each other very little. The risk for the bandwidth provider is that they provide forwarding service but aren’t properly paid, and the risk for the user is that they pay but do not receive service. Because the micropayments are very small, this risk is negligible.

Selecting a Bandwidth Provider

Selecting a bandwidth provider is an adversarial environment. The Orchid network protocol is built in such a way that the client should not need to trust the nodes that traffic is routed through.

The bandwidth consumer should be confident that when choosing a node, that node is incentivized to behave well. The likelihood that a given bandwidth provider is chosen is directly proportional to the amount of OXT staked on that provider’s behalf. The built-in withdrawal delay creates an opportunity cost for stakers. This disincentivizes malicious staking behavior.

Since the method for node selection currently requires offloading the scan() routine to an external Ethereum client, the client can verify correctness of the response by requiring merkle proofs of storage lookups.

There is also a secondary filtering mechanism that the client can use after the initial pool selection. This filtering is based on available metadata for each node (e.g., exit geolocation, latency/ping, node whitelists, etc.). While this does introduce some variability in the intended choosing probabilities, that variability is small enough to be ignored.

Probabilistic Micropayments

The probabilistic micropayments environment (a.k.a. the lottery) is adversarial as well. There is no trust assumed between the two actors for the correct functioning of the system.

Routing nodes (a.k.a. “bandwidth providers”) should have guarantees that the agreed upon probability of the ticket is enforced by the system. A random number is chosen by combining seeds from both the payer and the recipient. If that random number falls in a certain range (ratio in the code), the payment is transferred.

The protection against double spending and misbehavior from end users is enforced in the way of a an escrow fund on the payer’s side. The higher the escrow amount the bigger the incentive against misbehavior. The slashed amount is irretrievably left in the smart contract (i.e., “burned”).

5.3 Important Security Properties

OrchidDirectory

In the directory implementation we identified the following properties that should not be violated:

• Node selection is properly randomized:
  • A node’s likelihood of being chosen is directly proportional to the size of its associated stake.
  • It is impossible to otherwise influence the outcome of node selection.
• Node stakes can be withdrawn only after the built-in delay.
• There are no lock-up conditions:
  • The tree cannot get so big that operations requiring tree traversable exceed block gas limits.
  • The algorithm never creates orphaned nodes or otherwise violates proper tree structure.
• External actors cannot interfere with the system:
  • No one aside from node stakers can remove a node from the tree.
  • No external actor can affect the tree shape.

OrchidLottery

In the lottery implementation we identified the following properties that should not be violated:

• The probabilities for ticket payout are correctly enforced by the smart contract.
• Only a winning ticket recipient can redeem funds.
• A winning ticket can only be redeemed once.
• Penalty escrows are only slashed in the case of legitimate payouts exceeding the available funds.
• Payouts decay linearly according to their start and range parameters.
• Micropayment signers can only spend from funds they were authorized for.
• There are no lock-up conditions:
  • The payout routine is not affected by how many lotteries exist.
  • The payout routine is not affected by how many pots exist.
• External actors cannot interfere with the system:
  • No one but the respective funder or signer can take funds out of a pot.
  • No one but the respective funder can further fund a pot.

6 Issues

Each issue has an assigned severity:

• Minor issues are subjective in nature. They are typically suggestions around best practices or readability. Code maintainers should use their own judgment as to whether to address such issues.
• Medium issues are objective in nature but are not security vulnerabilities. These should be addressed unless there is a clear reason not to.
• Major issues are security vulnerabilities that may not be directly exploitable or may require certain conditions in order to be exploited. All major issues should be addressed.
• Critical issues are directly exploitable security vulnerabilities that need to be fixed.

if (name(stake.left_) == key) {
    current.right_ = stake.right_;
    current.after_ = stake.after_;
} else {
    current.left_ = stake.left_;
    current.before_ = stake.before_;
}

function good(bytes calldata shared, address target, bytes calldata receipt) external pure returns (bool);

bytes32 direct = current.parent_;
copy(pivot, last);
current.parent_ = stake.parent_;

if (direct == key) {
    Primary storage other = stake.before_ > stake.after_ ? stake.right_ : stake.left_;
    if (!nope(other))
        stakes_[name(other)].parent_ = name(last);

    if (name(stake.left_) == key) {
        current.right_ = stake.right_;
        current.after_ = stake.after_;
    } else {
        current.left_ = stake.left_;
        current.before_ = stake.before_;
    }
} else {
    if (!nope(stake.left_))
        stakes_[name(stake.left_)].parent_ = name(last);
    if (!nope(stake.right_))
        stakes_[name(stake.right_)].parent_ = name(last);

    current.right_ = stake.right_;
    current.after_ = stake.after_;

    current.left_ = stake.left_;
    current.before_ = stake.before_;

    stake.parent_ = direct;
    copy(last, staker, stakee);
    step(key, stake, -current.amount_, current.parent_);
    kill(last);

// Remember this key so we can update `pivot` later
bytes32 currentKey = name(last);

// Remove `current` from the subtree rooted at `stake`
step(currentKey, current, -current.amount_, stake.parent_);
kill(last);

// Replace `stake` with `current`
current.left_ = stake.left_;
if (!nope(current.left_))
    stakes_[name(current.left_)].parent_ = currentKey;
current.right_ = stake.right_;
if (!nope(current.right_))
    stakes_[name(current.right_)].parent_ = currentKey;
current.before_ = stake.before_;
current.after_ = stake.after_;
current.parent_ = stake.parent_;
pivot.value_ = currentKey; // `pivot` was parent's pointer to `stake`

function lift(bytes32 key, Stake storage stake, uint128 amount, address stakee, address staker) private {

lift(key, stake, -amount, stakee, staker);

step(key, stake, -current.amount_, current.parent_);

if (name(stake.left_) == key)
    stake.before_ += amount;
else
    stake.after_ += amount;

uint128 local = stake.amount_;
local += amount;
stake.amount_ = local;
emit Update(staker, stakee, local);

uint128 global = stakees_[stakee].amount_;
global += amount;
stakees_[stakee].amount_ = global;

return stake.before_ + stake.after_ + stake.amount_;

7 Tool-Based Analysis

Several tools were used to perform automated analysis of the reviewed contracts. These issues were reviewed by the audit team, and relevant issues are listed in the Issue Details section.

7.1 MythX

MythX is a security analysis API for Ethereum smart contracts. It performs multiple types of analysis, including fuzzing and symbolic execution, to detect many common vulnerability types. The tool was used for automated vulnerability discovery for all audited contracts and libraries. More details on MythX can be found at mythx.io.

The output of the MythX Pro vulnerability scan was reviewed by the audit team and no vulnerabilities were identified as part of the process.

7.2 Ethlint

Ethlint is an open source project for linting Solidity code. Only security-related issues were reviewed by the audit team.

Below is the raw output of the Ethlint vulnerability scan:

contracts/curator.sol
  35:8    warning    Provide an error message for require().    error-reason

contracts/directory.sol
  107:8     warning    Provide an error message for require().            error-reason
  141:4     error      "step": Avoid assigning to function parameters.    security/no-assign-params
  141:4     error      "step": Avoid assigning to function parameters.    security/no-assign-params
  176:8     warning    Provide an error message for require().            error-reason
  180:12    warning    Provide an error message for require().            error-reason
  202:8     warning    Provide an error message for require().            error-reason
  209:8     warning    Provide an error message for require().            error-reason
  211:8     warning    Provide an error message for require().            error-reason
  226:8     warning    Provide an error message for require().            error-reason
  226:35    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  228:8     warning    Provide an error message for require().            error-reason
  233:8     warning    Provide an error message for require().            error-reason
  233:35    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  244:8     warning    Provide an error message for require().            error-reason
  245:8     warning    Provide an error message for require().            error-reason
  305:8     warning    Provide an error message for require().            error-reason
  306:26    warning    Avoid using 'block.timestamp'.                     security/no-block-members

contracts/location.sol
  38:24    warning    Avoid using 'block.timestamp'.    security/no-block-members

contracts/lottery.sol
  66:8      warning    Provide an error message for require().            error-reason
  104:8     warning    Provide an error message for require().            error-reason
  111:8     warning    Provide an error message for require().            error-reason
  117:8     warning    Provide an error message for require().            error-reason
  131:8     warning    Provide an error message for require().            error-reason
  131:32    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  140:4     error      "take": Avoid assigning to function parameters.    security/no-assign-params
  153:12    warning    Provide an error message for require().            error-reason
  156:4     error      "grab": Avoid assigning to function parameters.    security/no-assign-params
  156:4     warning    Line exceeds the limit of 145 characters           max-len
  157:8     warning    Provide an error message for require().            error-reason
  158:8     warning    Provide an error message for require().            error-reason
  163:12    error      Only use indent of 8 spaces.                       indentation
  165:12    error      Only use indent of 8 spaces.                       indentation
  166:12    error      Only use indent of 8 spaces.                       indentation
  167:12    error      Only use indent of 8 spaces.                       indentation
  167:12    warning    Provide an error message for require().            error-reason
  167:28    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  168:12    error      Only use indent of 8 spaces.                       indentation
  168:12    warning    Provide an error message for require().            error-reason
  169:12    error      Only use indent of 8 spaces.                       indentation
  171:12    error      Only use indent of 8 spaces.                       indentation
  172:0     error      Only use indent of 8 spaces.                       indentation
  175:20    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  176:64    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  182:8     warning    Provide an error message for require().            error-reason
  200:22    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  214:8     warning    Provide an error message for require().            error-reason
  215:8     warning    Provide an error message for require().            error-reason
  215:31    warning    Avoid using 'block.timestamp'.                     security/no-block-members
  219:8     warning    Provide an error message for require().            error-reason

✖ 12 errors, 38 warnings found.

7.3 Surya

Surya is an utility tool for smart contract systems. It provides a number of visual outputs and information about structure of smart contracts. It also supports querying the function call graph in multiple ways to aid in the manual inspection and control flow analysis of contracts.

Below is a complete list of functions with their visibility and modifiers:

8 Sūrya’s Description Report

8.1 Files Description Table

8.2 Contracts Description Table

8.3 Legend

Appendix 1 - Disclosure

ConsenSys Diligence (“CD”) typically receives compensation from one or more clients (the “Clients”) for performing the analysis contained in these reports (the “Reports”). The Reports may be distributed through other means, including via ConsenSys publications and other distributions.

The Reports are not an endorsement or indictment of any particular project or team, and the Reports do not guarantee the security of any particular project. This Report does not consider, and should not be interpreted as considering or having any bearing on, the potential economics of a token, token sale or any other product, service or other asset. Cryptographic tokens are emergent technologies and carry with them high levels of technical risk and uncertainty. No Report provides any warranty or representation to any Third-Party in any respect, including regarding the bugfree nature of code, the business model or proprietors of any such business model, and the legal compliance of any such business. No third party should rely on the Reports in any way, including for the purpose of making any decisions to buy or sell any token, product, service or other asset. Specifically, for the avoidance of doubt, this Report does not constitute investment advice, is not intended to be relied upon as investment advice, is not an endorsement of this project or team, and it is not a guarantee as to the absolute security of the project. CD owes no duty to any Third-Party by virtue of publishing these Reports.

PURPOSE OF REPORTS The Reports and the analysis described therein are created solely for Clients and published with their consent. The scope of our review is limited to a review of Solidity code and only the Solidity code we note as being within the scope of our review within this report. The Solidity language itself remains under development and is subject to unknown risks and flaws. The review does not extend to the compiler layer, or any other areas beyond Solidity that could present security risks. Cryptographic tokens are emergent technologies and carry with them high levels of technical risk and uncertainty.

CD makes the Reports available to parties other than the Clients (i.e., “third parties”) – on its website. CD hopes that by making these analyses publicly available, it can help the blockchain ecosystem develop technical best practices in this rapidly evolving area of innovation.

LINKS TO OTHER WEB SITES FROM THIS WEB SITE You may, through hypertext or other computer links, gain access to web sites operated by persons other than ConsenSys and CD. Such hyperlinks are provided for your reference and convenience only, and are the exclusive responsibility of such web sites’ owners. You agree that ConsenSys and CD are not responsible for the content or operation of such Web sites, and that ConsenSys and CD shall have no liability to you or any other person or entity for the use of third party Web sites. Except as described below, a hyperlink from this web Site to another web site does not imply or mean that ConsenSys and CD endorses the content on that Web site or the operator or operations of that site. You are solely responsible for determining the extent to which you may use any content at any other web sites to which you link from the Reports. ConsenSys and CD assumes no responsibility for the use of third party software on the Web Site and shall have no liability whatsoever to any person or entity for the accuracy or completeness of any outcome generated by such software.

TIMELINESS OF CONTENT The content contained in the Reports is current as of the date appearing on the Report and is subject to change without notice. Unless indicated otherwise, by ConsenSys and CD.