# vVv investment architecture :::warning Not final, could contain errors in logic. Some requirements of the system are also still unknown or unclear. Subject to change. ::: :::danger Custodial functionality currently not included in the investment architecture as it's still unknown how this will take shape as part of the overall system architecture. ::: The current implementation is _almost_ entirely on-chain but the verification of an off-chain signature during investment (for eligibility and allowance) and the extensive admin functionality mean that not much decentralisation is lost by considering a (more) hybrid approach. A diagram describing this hybrid architecture can be found [here](https://s.icepanel.io/6i8RonJV6luAxR/FN0G). A diagram of the entire vVv system architecture is also available. ## On-chain components I suggest separating the blockchain functionality into two, or at most three, components. This improves readability but also means these components can be replaced if necessary. It also makes the system more flexible. ### Investment ledger `ethereum` The investment ledger is responsible for accepting payment tokens from investors. Refund functionality is also available. Eligibility is done off-chain whenever possible, the component trusts the centralised part of the system completely. Only time / race condition sensitive conditionals are evaluated on-chain. Administrators will be able to withdraw funds. The state just concerns itself with investment transaction data. This can be as concise as: ``` struct Investment: KYC address Investment round ID Payment token Amount Investment opportunity (i.e. project) ID ``` The full data of these investment rounds and their corresponding project does not need to be stored on chain if the centralised component is trusted. :::warning Measures against replay attacks and signatures based on outdated state should be taken. Evaluate on-chain when impossible. ::: #### Investment ledger read-only replica `avalance` `arbitrum` `polkadot` `cosmos` To allow the token distribution contract to function on chains other than Ethereum we require a read-only replica of the (partial) investment ledger component. Essentially this means we want to allow administrators to persist the investment ledger state to contracts on the various other blockchains. The admin can do this at any given moment, most likely when an investment round for a project not on Ethereum finishes. The admin signs the validity of this state. The API will facilitate this process. ### Token distribution `ethereum` `avalanche` `arbitrum` `polkadot` `cosmos` This component is responsible for the distribution of the (vested) project tokens. An investor can make a claim such as ``` struct Claim: KYC address amount investment round ID ``` The token distribution contract can then query the state of the investment ledger or its read-only replica (depending on the chain) to calculate the allowance of the caller. As such, an instance of the contract is deployed on each supported blockchain. ### Alias management :::info This is optional and I'd argue for its removal. The centralised part of the system is already completely trusted during investment so we may as well not store this data on-chain. I don't think it's critical for transparency. Downside is that claim will require a signature for aliases but **not** when claiming as the KYC address (at least not on account of this feature). ::: There's two options here but I think the current approach of creating a mapping between KYC address and aliases is the correct approach. I'd just store the mapping off-chain or alternatively as a separate component, kinda like an operator filter. The other option would be to require a signature signed by the KYC address that states the alias is authorised. This is probably more expensive in the long run though as the amount of times an alias is _used_ is probably higher than the times it's created or deleted and signature verification is more expensive than checking against a mapping. **To reiterate though: this component is excluded from the architecture design. It's just described in this document to provide additional information on the variety of options.** ## Off-chain components ### API #### Alias management module :::warning KYC address ingress out of scope. ::: :::warning It's unknown whether this alias system will be used in any other parts of the overall system, it's currently assumed that it won't be. ::: Responsible for alias management: creation, deletion, viewing, and modification. Aliases are addresses that are allowed to invest on behalf of the KYC address. KYC address authentication is required for alias management. #### Signature creation Responsible for the creation of the signatures required to make investments as well as claims. Evaluates the eligibility of the caller and the state of the investment system and signs the resulting data required to make investments and claims on the on-chain components. #### Investment project and rounds CRUD Allows authorized admins to manage investment projects and their rounds. Also responsible for making the project and investment round collections browsable for both investor as well as admin. #### Transaction and claims insight Provides the investor with functionality to get detail insight into their previous transactions, whether it be claims, investments, or refunds. Also enables the user to get insight into the performance of their portfolio. The data these views are based on are ingested through Pulse. #### Proxy EOA creation Creates proxy externally owned accounts (EOAs) to be used for project token deposits. Project tokens will be linked to their investment rounds using these addresses. The API will create the correct EOA depending on the chain ID of the corresponding investment round. ___ ### Pulse Responsible for batch processing tasks. In the case of the investment system Pulse is responsible for querying the sub graph(s) to sync the blockchain state to the API. Specifically investment, claim, and refund transactions will be processed. ___ ### Subgraph(s) One or multiple subgraphs as part of The Graph system dependency. These subgraphs define how we index investment and preprocess transaction events. ___ ### Web Application :::info A detail description of this service has been postponed. See the [related epic](https://linear.app/vvvfund/issue/VVV2-35/investment-web-app-features) on Linear for more information. A higher level design remains available as part of the architecture diagrams. ::: ## Challenges ### Distributing one project token based according to different vesting schedules Both the "on-chain approach" as well as the proposed hybrid architecture need to deal with the challenge of identifying project token allocation of multiple origins. This boils down to the need of an identifier to identify the source of the transaction (i.e. which vesting schedule). #### On-chain approach The on-chain approach has two options: ##### 1. Proxy contract wallet deployments. An ERC-20 transfer has 4 pieces of data: 1. The destination address 2. The origin address 3. The amount 4. The date If #2 - #4 are insufficiently unique to identify the source of the transaction we need to use #1 as that's the only data we control. This requires proxy deployment. ##### 2. Protocol agreement A different protocol needs to be agreed on between sender and recipient (vVv). If that can be done the available solutions are varied. They all come down to adding a piece of metadata to identify the source of the transaction though. #### Hybrid architecture The proposed architecture has a third option: ##### 3. Off-chain proxy addresses Upon investment round creation we can generate a private key. When the project token is known (not sure if this is immediate) `approve` can be used to allow the compensation contract access to the funds. The public address corresponding to the private key can be used to receive funds. This is likely cheaper than manual fund deployment. ### Relaying investment ledger state to supported blockchains Each supported blockchain will contain their own version of the token distribution contract. As such, each of these blockchains need access to the (partial) state of the investment ledger on Ethereum and therefore each chain needs a smart contract to submit this state to. This state needs to be submitted by one or multiple relayers. Below are three identified options to facilitate this, each with their own trade-offs. To better understand these trade-offs we’ll first specify the security risks. #### Security risks :::info It'd be prudent to properly define a threat-landscape for the vVv organisation or at least the entire system. However, this is currently not a defined requirement or priority. ::: * By using a first-party service as a relayer there’s **no increased trust** placed on the vVv platform. * The admin can already rug with all investments * Compensation could never be provided * In short, the vVv system is inherently trusted * By using a first-party service as a relayer there’s **an increased risk** if the service were exploited. * It could be made to write `X` has invested `Y` ETH for project `Z` to one of the blockchains while `X` has not done this. -> `X` could then withdraw without having made an investment. * In reality this simply relates to software and process security, which is not a novel problem nor can it be ignored regardless of the cross-chain communication implementation. Nevertheless, risk should be minimised where it occurs. **Option 2 is the most suitable given the current requirements, derived threat landscape, and system context.** #### Options ##### 1. First-party centralised service as a trusted relayer The system reads the state of the Ethereum investment ledger at given intervals (e.g. when a round has finished). The system submits the investment transactions (investments and refunds) to a given chain which ingests the resulting state. There’s assumed to be sufficient time lag between state commitment (investment conclusion) and reading (token withdrawal) to allow for error detection and correction. This could be automated. Because of this time lag the impact of malicious transaction submission without it being caught is significantly diminished: the transaction would have to built upon the previously verified state. This does not mean the risk is non-existent though, it’s still an **increased risk** over a single-chain system. ##### 2. First-party centralised service relayer transactions signed by admin This solution uses a service in the vVv system as a relayer. The difference with the previous option is that a resulting state itself is persisted to the given chain and this state is **signed by an administrator**. This is done manually (e.g. when the investment round is complete and the funds are likely removed from the investment ledger). Having the administrator sign the state has two benefits: 1. Because there’s already complete trust placed on the admin there’s **no increase** in risk using this option (aside from that which is inherit with the complexity of a multi-chain system). 2. The increase in workload for the administrator should be negligible as the removal of funds of the investment ledger was always going to be a manual process. ##### 3. Decentralised relayers submitting state by consensus This solution involves using one or multiple providers of decentralised relayers. The benefit of this approach is that the state submitted to the given blockchain can be considered correct and verified without manual intervention. This is of course based on the assumption that the consensus protocol provides sufficient trust in the relayers and the resulting transaction. The drawbacks are those that are inherit with relying on third party services. It’s assumed these are known so they won’t be reiterated here, however, the limitation of supported blockchains by the third party and the latency are worth highlighting. It's also assumed there's an increased cost. This option is ill-advised given the small one-directional use case and the existing trust that’s inherit to the vVv system. As the risk is **identical** to option 2 it’s hard to justify the trade-off. ## Thoughts ### On prioritising off-chain computation * Much more gas efficient. * Some administrative work can be free right up to the start of an investment round ### On separate investment and compensation contracts * Easier to maintain, they're three distinct responsibilities. * Generic, e.g. allows for different forms of compensation if ever required.