# Fetcch Docs

# Fetcch Payment Connectivity Network Protocol Specs

## Introduction

Fetcch Payment Connectivity Network or FPCN is a network that is focused on providing users with transaction identities

## Concepts

These are concepts used in FPCN

### Identities

The Fetcch Identities must ensure that users

- own their identity
- can transact between 2 or more identities or entities on the blockchain
- are quick and easy to setup
- default.address can be changed without losing ownership of identity

Identity namespace is unique for each provider on the network, so a user can own `satyam@metamask` and another user can own `satyam@phantom`, both will be considered different and will not interfere with each other.

Fetcch achieves this by having a separate identity namespace for each provider called **Provider Registry**. This is a smart contract on ethereum which issues ids to users, these ids will be alphanumeric ([A-Z a-z 0-9]).

Identities metadata is stored on a decentralized storage solution and subsequently stored on **Provider Registry** alongside

{
	"id": "satyam@fetcch",
	"pid": "1213edscxz",
    "pidType": "IPFS",
	"address": {
		"default": "0x0000",
		"others": ["0x0000", "0x0000"]
	},
	"merkelRoot": "0x000000",
	"signature": "0x000000" // only if msg.sender isn't default.address
}

With `merkleRoot` anybody can verify if the data on `pid` (or as we call it **Proof of ID**) is in the correct format, contains a valid signature, and is complementary to previous state of the ID (if updated)

Fetcch Identities are purely decentralized, secure, and ownership-enabled because we use signatures at every step of the process and generate cryprographic proofs for easier verification by anyone.

If `default.address` is hacked, then to recover ID, a user has to get 2/3 signatures of `others` addresses, with this they can change `default.address` and gain back access to their ID OR else `default.address` can set a recovery address which can be multisig or a friend, and that recovery address can update `default.address` in case of a hack.

### Signed Messages

FPCN supports almost all of the major blockchains and many blockchains have different signing algorithms, we support verification of all of those algorithms, and signatures should be in the format

{
    "id": "satyam@fetcch",
    "message": {
      // will be stringified id  
    },
    "signature": {
        "signature": "0x000",
        "type": "ecdsa",
        "timestamp": "",
        "pubKey": "0x00"
    }
}

This helps owners retain ownership of their own identities while doing off-chain stuff or relying on providers/relayers to do on/off-chain stuff.

### Provider

A Provider can be a wallet or dApp or anyone who wants to issue their own branded identities to their users and connect to a vast network of similar but different providers and their users.


Each provider is connected to the other one and subsequently their users also thus creating a decentralized, p2p network of wallet ids and providers.

Provider needs to first register and acquire their namespace, these namespaces should be unique and alphanumeric. They can acquire this from **Fetcch Registry** (more on this below).

The provider acts as a hub for a user to connect with other users from other hubs (providers). They also act as a relayer, with valid signatures, and they can edit user data on **provider registry** contract.

The provider also has the option to mint NFTs to `default.address` of anyone who registers an ID on their namespace. These will directly be handled by the FPCN Network.

> 💡If you think enough, FPCN works on a Hub & Spoke model, wherein a Provider acts as a hub and users as spoke!

### Data Sources

Data sources are storage solutions where a provider can decide to store, it can be but is not limited to

- IPFS
- Arweave

Metadata is stored on these storage solutions and anchored on ethereum or any other blockchain.

Right now, we only support ethereum for anchoring metadata as we are working on building a more robust and trustless network, we will continue to add support for more and more blockchains in the future!

### Indexer

All of the data is stored on a decentralized storage solution and ownership is managed on ethereum.

We can't run heavy computation work on blockchains due to their technical limitation and that's why we've built an indexer which enables us to do exactly that.

Fetcch Indexer is a completely trustless technological piece that exposes a GraphQL API for developers to access various add-on functions of FPCN.

> [FPCN GraphQL API Documentation](https://sk1122.notion.site/FPCN-API-8d21173910734876abaceca0480a5064)

### Payments

FPCN simplifies payments for degens, everyday users, and your grandmother too. We do this by enabling transactional communication between 2 or more FPCN IDs.

FPCN IDs are connected to various addresses from various blockchains and this helps in cross-chain transactions.

FPCN supports 3 types of transaction

- P2P Transaction
- Cross Chain
- Same Chain
- Payment Request Transaction
- Cross Chain
- Same Chain
- Cross Chain Contract Execution

#### P2P Transaction

*P2P Cross Chain Transaction*
*P2P Same Chain Transaction*

When an ID sends some token to another ID, it is constituted as a P2P Transaction.

P2P transactions can either be the same chain or cross-chain depending on addresses used from ID.

A payer can choose which chain and token to use and the recipient will receive it either on their `default.address` or if enabled `forcedSameChainPayment`, protocol chooses any other address connected to the ID which has the same chain as the payer.

Cross-chain transactions are fulfilled using bridges in between, so on the frontend, `satyam@metamask` is paying `ray@phantom` but in reality `0x312312...` is paying `5fwerfwecn...` in USDC from Ethereum to Solana using XXX Bridge.

#### Payment Request Transaction

A dApp can send a payment request to any ID from FPCN which that ID can fulfill asynchronously, this can either be a same-chain or cross-chain payment.

A Payment request can enable dApps to receive payments from users on a subscription basis or it can be used in a single-click checkout system.

The payment request is of format

{
    "payee": "satyam@metamask",
    "payer": "ray@phantom",
    "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "chain": "2", // fetcch chain id
    "amount": "1000000", // in smallest denomination
    "message": "Payment for your yeezy sneakers",
    "label": "Yeezy#7813",
    "data": "", // if contract call
    
    // added after resolving payment request
    "transactionHash": "0xa66addcaf87f6f3135c982296eda74af4bb82cf67ec84065833bdff160943c44",
    "dstTransactionHash": "", // if cross chain transaction
    "fromChain": "2",
    "fromToken": "0x8f7116ca03aeb48547d0e2edd3faa73bfb232538"
}

A Payment Request can be dApp to Peer or dApp to dApp or Peer to Peer. It can also be either a simple token transfer or a complex transaction, it can be a cross-chain contract or same chain.

#### Cross-Chain Contract Execution
*Cross Chain Contract Execution Flow*

Cross Chain Contract Execution helps IDs to interact with smart contracts on a blockchain without requiring to have tokens or gas on that chain.

For ex. a user on Solana can LP into uniswap pools without touch bridges or an ethereum user posts on a lens from their polygon wallet without requiring a polygon token or interacting with a bridge!

In CCCE, a user uses dApp and initiates a transaction, it will be a smart contract call, Wallet will prompt which chain to use, and if it's different, wallet signs a message from the user confirming that they are ready for this transaction. ID's tokens are swapped using FPCN and the contract is called dApp's chain.

> 💡FPCN will also support IDs for dApps in near future and that will simplify this process by a lot!

## Smart Contracts

### Fetcch Registry
**Fetcch Registry** contract is responsible for providing unique namespaces for providers. Providers will acquire namespaces by sending this data

{
    "metadata": "",
    "metadataType": "",
    "owner": "",
    "name": "",
    "logo": ""
}

On successful registration this contract deploys a new **Provider Registry** contract for providers where identities can be registered and modified.

### Provider Registry
**Provider Registry** contract is responsible for registering identities by the provider. This contract gets deployed after a provider has acquired a unique namespace. The following input data is needed for registration of ids by the provider.

{
	"id": "satyam@fetcch",
	"pid": "1213edscxz",
    "pidType": "IPFS",
	"address": {
		"default": "0x0000",
		"others": ["0x0000", "0x0000"]
	},
	"merkelRoot": "0x000000",
	"signature": "0x000000" // only if msg.sender isn't default.address
}

Ownership of identities will be with their respective `default.address` and a multisig of `other.address`.
Provider can modify data on any identity with valid signatures from either of the two.

### Proof of ID

**Provider Registry** needs **Proof of ID** to be able to create new IDs in their namespace.

**Proof of ID** is data in format

{
	"id": "satyam@fetcch",
	"pid": "1213edscxz",
    "pidType": "IPFS",
	"address": {
		"default": "0x0000",
		"others": ["0x0000", "0x0000"]
	},
	"merkelRoot": "0x000000",
	"signature": "0x000000" // only if msg.sender isn't default.address
}

Anybody could verify IDs using `merkleRoot` present on the chain.
`signature` is needed when PID is updated by non `default.address` as `msg.sender`

### Access Controls Rules
- default.address has ownership of a id
- other address can change default.address by a multisig signature
- provider can change PID with valid signatures
- each provider will have a different contract
- each ID will be in format, it will be list of that format, with latest being the last element
- anybody will be able to verify PIDs data using merkle proof in format

### Security Considerations
**Default Function Visibility**
In solc < 0.5.0 functions are public by default if a function visibility type is not specified. If a developer neglected to specify the visibility and a malevolent user is able to perform illegal or unintentional state changes, this might result in a vulnerability.
Explicit function visibility specifiers are necessary for solc >= 0.5.0.

**Access Control**
Access controls define the restrictions around privileges and roles of users in an application. Access control in smart contracts can be related to governance and critical logic like minting tokens, voting on proposals, withdrawing funds, pausing and upgrading the contracts, changing ownership, etc.

**Uninitialized Storage Pointer**
The EVM can store data as storage, memory, or calldata. Uninitialized local storage variables may point to unintended contract storage locations, creating security holes.
This problem has been systematically fixed as of compiler version 0.5.0 and above since contracts with uninitialized storage references no longer compile.

### Upgradability in Smart contracts
Smart contracts can be upgraded to modify their code, while preserving their address, state, and balance. This allows to iteratively add new features to the project, or fix any bugs found in production.
We use UUPS(Universal Upgradeable Proxy Standard) for upgrading smart contracts.
We don't have a schedule to upgrade contracts but do it on per need basis. Contract versions start from V1.0.0, and based on what we have changed, patch or minor or major, we'll change version names accordingly.

# Fetcch Block

## Overview

- Fetcch block enables faster cross-chain any token to any token exchanges by leveraging communication layers in place of bridges.
- Fetcch block initiates swaps for the desired token using dex aggregator and stable coin liquidity pools deployed on all of the most popular chains instead of requiring users to lock or burn tokens and then mint them on the target chain.
- Process: For example user wants to swap APE coin on Ethereum for Matic on Polygon.
1. The user will select these desired pairs and chains.
2. Fetcch block then swaps APE coin for stablecoin in the source chain's liquidity pool and sends a message using messaging layer to the destination chain.
3. The stablecoin is then swapped from the liquidity pool to Matic and transferred to the user's wallet after receiving the message on the destination chain.


- Users can now exchange any token for any token in a significantly shorter amount of time without having to burn or mint new tokens or pay for gas on the destination chain.

## Smart Contracts

- **Bridge Adapter**
- By passing the necessary data, such as source chain data, destination chain data, and dex data, this contract is in charge of initiating a swap. It then communicates with other contracts.

    SwapData (
        address _refundAd;
        DexData _dex;
        FromChainData _fromChain;
        ToChainData _toChain;
        address _receiver;
        bytes _extraParams;
        uint16 _commLayerID;
    )

- **Communication Layer Aggregator**
- This is an aggregator contract that interacts with required communication layers like axelar and layerzero for sending messages across chains.

    sendMsg (
            uint256 _id,
            address _destinationAddress,
            bytes _payload,
            bytes _extraParams
        )

- **Dex Aggregator**
- The 1inch Aggregation Router, which facilitates token exchanging on the same chain, is integrated into this contract.

    swap (
            IAggregationExecutor executor,
            SwapDescription desc,
            bytes data
        )

- **Liquidity Pools**
- Liquidity Pools are maintained on the source and destination blockchains, where users deposit funds on the source chain and withdraw funds from the destination chain, after deducting protocol and gas fees.

    deposit (
            address _tokenIn,
            address _receiver,
            uint256 _amount,
            uint256 _commLayerId,
            ToChainData _toChain,
            DexData _dex,
            bytes  _extraParams
        )

    release(bytes _swapData)

- **Fee Library**
- This contract is responsible for calculating equilibrium fees and rewards based on the liquidity available in pools and swap amounts.

    getEqRewards (
            address _pool,
            address _token,
            uint256 _amount,
            uint256 _suppliedLiq,
            uint256 _IP
        )

    getEqFees (
            address _pool,
            address _token,
            uint256 _amount,
            uint256 _suppliedLiq
        )

## Communication layers

- **LayerZero**
- An omnichain interoperability protocol called LayerZero is intended for quick message transmission between chains. Delivering messages authentically and reliably is ensured by LayerZero, and trustlessness can be customized.
- **Axelar**
- For Web3, Axelar offers safe cross-chain communication. Delegated proof-of-stake is the foundation of Axelar network security; a permissionless, dynamic validator set applies a consensus method comparable to the networks Axelar connects.

## Dex Aggregator

- **1inch**
- The 1inch Aggregator finds the pathways for exchanging tokens. By dividing the order between various protocols (DEXs), it uses a routing algorithm to determine the most effective paths for a token swap and obtain the most tokens for the user.

## Dynamic Fee Structure

- As transfers occur, excessively one-sided demand can cause pool imbalances, with high liquidity in well-liked source pools and low liquidity in pools with strong demand as destinations. Bridge transfers won't succeed in these situations unless the liquidity is balanced again.
- Hence we use the dynamic fee model by [hyphen](https://www.notion.so/On-Chain-Payment-Request-2a07409aa1ff4db08437cb278c205847). In this model the transfer fee is determined by pool available liquidity, pools are independent of external AMMs, and native bridges are not required to carry out rebalancing.

## Security Measures

- Liquidity Pools
- Since liquidity pools are a favourite target for hackers, we use the tokenized vault standard ERC-4626 to protect pools from outside threats. Vaults are smart contracts that accept token deposits and use those tokens to perform actions that give the depositor token rewards.
- Cross-Chain Messaging
- It is crucial to make sure that no messages are tampered with as they are sent from the source chain to the destination chain since fetcch uses messaging layers rather than bridges for cross-chain communication. Therefore, for cross-chain messaging, we use secure communication layers like layerzero and axelar.
- Internal Audits
- In addition to these security precautions, we perform internal audits on a regular basis that involve both manual and automatic security testing while taking into consideration all known solidity attack vectors and past bridge breaches.

## Misc

- Tools Used
- Foundry
- We utilize foundry to manage dependencies, compile, run test cases, and deploy smart contracts.
- Slither
- Slither is what we use to analyze smart contracts statically. It executes a number of vulnerability scanners, outputs visual information about the terms of the contract, and offers an API for quickly creating unique studies.
- MythX
- For the security examination of smart contracts, we use MythX. Static analysis, symbolic execution, and input fuzzing are used to find security flaws and ensure that the smart contract code is valid.
- Tenderly
- Tenderly is used for smart contract monitoring, alerting, debugging, and simulation in real time.

## Contract Addresses

- Testnet
- Goerli
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex
- Mumbai
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex
- BSC Testnet
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex
- Fuji
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex

- Mainnet
- Ethereum
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex
- Polygon
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex
- BSC
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex
- Avalanche
- Bridge
- Messaging Providers
- Liquidity Pools
- Dex