Introduction Last updated: 2021-07-16

Welcome to Umbria! This documentation page contains comprehensive documentation of the Umbria DeFi ecosystem. If you are just starting with Umbria, we recommend reading up on the Protocol Overview or FAQ first.

To keep up-to-date with news and updates, check out the blog. Enter the discord channel to participate in discussion.

Get Started

If you just want to use the platform, select from the below features.

Token Swapping

Swap assets cheaply on the Umbria Decentralised Exchange (DEX).

Liquidity Provision

Lend your assets to the Umbria DEX and earn incredibly high interest.

Farming

Earn UMBR by staking the LP tokens you received for providing liquidity.

Cross-Chain Bridge

Move your crypto-assets cross-chain, from one network to another, quickly and cheaply.

Use the sidebar to pinpoint specific details about the protocol and usage of Umbria.

Protocol Overview

The Umbria ecosystem has three major protocols:

  1. A Cross-chain Asset Bridge; enabling the transfer of assets between otherwise incompatible blockchains and cryptocurrency networks.
  2. A Staking Pool, where users can earn interest on their crypto-assets by providing liquidity to the bridge. Liquidity providers of UMBR earn a portion of all fees generated by the bridge.
  3. A Decentralised Exchange (DEX); and automated liquidity protocol powered by a constant product formula, deployed using smart contracts, governed entirely on-chain.

Both protocols of the Umbria ecosystem work in tandem to provide asset migration between cryptocurrency networks seamlessly, and a very fast, low-fee DEX for trading assets, powered by Polygon PoS Chain (Ethereum Scaling Solution). The Umbria ecosystem acts as a platform, for moving funds freely between cryptocurrency networks, and for trading those assets in one place.

Note

The Umbria ecosystem provides cross-chain transactions and a decentralised exchange (DEX).

Token Swapping

The Umbria DEX does not function like a traditional asset exchange, such as a stock market with an order book. Its protocol invokes and maintains an automated market maker mechanism, which updates respective token values, with each trade. Tokens available to swap are grouped in pairs. The liquidity (amount of available trading volume) of each token pair is determined by a liquidity pool, wherein lenders lock their funds into the protocol and earn fees every block, when swapping takes place. Whenever one token is swapped for another, the Umbria Exchange uses the constant product formula to calculate the value of each token with respect to the other in the pair, which ultimately determines the price.

Umbria provides a DEX for swapping ERC-20 tokens. The swap value of tokens within the DEX is calculated by the protocol's underlying smart contracts in real-time, and displayed to the user before execution. When the user executes the swap, their token balances are updated immediately. The Umbria Exchange also updates the swap value of the two tokens.

The Umbria protocol can support any ERC-20 standard token pairs, but liquidity must be provided to facilitate trading.

Executing a Swap

Token swapping is currently supported on the Umbria DEX on the Polygon PoS Chain.

The DEX's swapping functionality is handled by the smart contracts deployed on-chain. The Pair contract handles logic regarding the state of each pair, and provides functionality to the token pairs. The state of each token pair is updated with every swap.

Sending Tokens

To initiate a swap, using the Umbria DEX front end, the user must first approve the tokens to be spent. Once approval has been granted, the user can then execute the swap.

The Umbria Exchange is deployed on the Polygon PoS Chain, which greatly reduces gas fees, and speeds up execution time. The on-chain fees are very low when sending tokens to the DEX to invoke a swap, when compared to Ethereum. The Polygon PoS Chain is also capable of completing a swap in seconds, rather than minutes or hours when compared to Ethereum.

Once executed, the transaction is verified by the network, inheriting the network's robust cryptographic assurances. Past swaps are immutable, due to the nature of the underlying blockchain infrastructure.

Receiving Tokens

When a swap is executed, the received tokens immediately show up in the user's wallet. A user can track the progress of a swap, by consulting the relevant blockchain explorer. The blockchain explorer provides details on the swap, including information regarding its finality.

For the Polygon PoS Chain, Polygon Explorer tracks the progress of all swaps.

Liquidity Provision

Users can provide liquidity to the Umbria DEX and / or the Narni Bridge. The DEX and bridge have slightly differing liquidity provision structures.

The Narni bridge requires a user to deposit only one kind of ERC-20 token, to earn fees when other users bridge their assets across chains. The DEX requires both assets of a particular token pair, to earn fees whenever anyone swaps between those assets on the DEX.

Note

You can provide liquidity to the Umbria DEX or the Narni Bridge.

Exchange Liquidity

Liquidity providers can provide liquidity to the Umbria DEX and earn interest on their crypto assets.

The Umbria Exchange is an automated market maker, which borrows asset liquidity from users who wish to earn interest on their assets. Users lend a pair of assets, to token pools. The assets are used to facilitate trading between other users. When a trade occurs, liquidity providers are awarded their share of a 0.2% trading fee. The volume of liquidity in each pool determines the rates and slippage when trading assets in that pool. The greater the liquidity in the pool, the lower slippage each swap will cause.

Liquidity providers earn fees whenever a swap takes place within that pair. They can remove their liquidity at any time and automatically receive the accrued fees in their wallet.

Users can create a new token pair by being the first to add liquidity to that token pair's liquidity pool. It is possible to create a liquidity pool on the Umbria DEX for any ERC20 standard token.

Bridge Liquidity

Liquidity providers can provide liquidity to the Umbria Narni Bridge and earn interest on their crypto assets.

The Umbria Narni Bridge enables the cross-chain migration of users' assets between two networks by holding liquidity on both networks. The bridge mechanism receives an asset "with one hand" on the starting network and "gives with the other hand" to the same wallet address on the provided network. This enables certain types of cross-chain transactions which would otherwise be rendered impossible by constraints imposed by network validators, namely cost and speed. The Narni bridge negates these cumbersome elements by calling on user-provided asset liquidity on the various networks.

Users can provide liquidity to the Narni bridge, and earn interest on their assets whenever anyone brides their assets between cryptocurrency networks. Unlike the Umbria DEX and many liquidity provision paradigms, users only need to provide liquidity for one asset at a time to earn interest.

Whenever someone bridges assets between two cryptocurrency networks using the Umbria Narni Bridge, they receive their share of a 0.2% fee.

Liquidity providers can remove their liquidity at any time from the network to which they provided the asset. The user must pay the transaction fee for the bridge to return their asset to them. Users do not need to harvest the interest earned by their liquidity manually. The interest earned on their pooled liquidity is automatically added to their staked liquidity every five minutes. When a user removes their liquidity from the pool, they automatically harvest the interest earned by their assets.

Farming

Umbria introduced farming as an incentive to provide liquidity to the Umbria DEX. Whenever a user adds liquidity to the DEX, they receive a liquidity provision token (LP Token), which acts as a receipt and can be used to redeem the underlying assets. Users can stake the certain LP tokens in a system known as Farming, to earn bonus UMBR tokens every block.

Note

You can farm UMBR by staking your UMBR-MATIC LP tokens in the Umbria MATIC Farm or by staking your UniV2-UMBR-ETH LP tokens from Uniswap in the Umbria Ethereum Farm.

Entering The Farm

Users automatically start farming UMBR when they stake their LP tokens in the respective farm. Users pay a small network fee for interacting with the farm and adding their LP tokens. The assets will earn UMBR every block until the user removes their LP tokens. The LP tokens are still earning fees on the underlying assets while being staked in the farm.

Harvesting

The UMBR accrued by staking the LP tokens in the farm is increased every block. A user can choose to harvest the UMBR they have earned by pressing the Harvest button in the farm, and paying a network fee to interact with the smart contracts which underpin the farm.

Exiting the Farm

When a user exits the farm, they automatically harvest the remaining UMBR earned for providing the LP tokens. The user can enter and exit the farm at any time, but must pay the network fee for interacting with the underlying smart contracts.

Connect

Umbria provides a connection portal to connect your Metamask wallet to any EVM compatible chain. This enables quick wallet configuration for ease of use, when dealing with multiple assets across chains.

Note

You can connect to any EVM compatible chain using the Connect Portal.

Connect Portal

Users can use the Connect Portal to connect their Metamask wallet to any EVM compatible network

The Umbria Connect portal provides an easy-to-use network connection interface for every major EVM compatible chain. By using the connect portal, users can quickly configure their wallet to interact with their assets on the desired network, without having to manually configure RPC connections. The connect portal also provides useful information regarding the connected chain, such as chainID and a link to the network's native blockchain explorer, if such an explorer exists.

Supported Chains

You can find a JSON encoded list of all supported networks / chains here.

Cross-Chain Bridge

The Umbria Narni bridge is a cross-chain asset bridge, enabling the migration of assets between cryptocurrency networks. Users can seamlessly move their assets across chains using the Narni bridge's liquidity bridging model. Bridging is incredibly quick and incurs extremely low fees in comparison to validator-driven bridges.

Note

You can migrate your assets across chains using the Umbria Narni Bridge.

Bridging Assets

The Narni bridge supports a distinct set of assets on a distinct set of networks.

UMBR MATIC ETH GHST USDT USDC WBTC
MATIC MAINNET
ETHEREUM MAINNET
BINANCE SMART CHAIN SOON SOON SOON SOON SOON SOON SOON
SOLANA SOON SOON SOON SOON SOON SOON SOON
AVALANCHE SOON SOON SOON SOON SOON SOON SOON

Users can migrate the above assets across networks using the Narni bridge.

Bridge Pool

Users can provide asset liquidity to the Narni Bridge Pool, and earn high interest on their assets whenever someone uses the bridge to migrate between cryptocurrency networks. The bridge uses supplied liquidity to facilitate asset migration (bridging) across networks. Whenever bridging occurs, liquidity providers earn their share of a 0.2% bridging fee. Liquidity providers can provide a single asset to the bridge, and earn interest in the native asset they supplied.

New assets will be added to the bridge, and new liquidity pools with distinct APYs will become available over time. Assets that are frequently bridged accrue higher fee generation for the liquidity providers. There is an incentive to provide stablecoins, due to the frequency of their use in arbitrage and trading. Unlike traditional liquidity provision and farming, stablecoins offer a high yield.

Bridge Harvesting

Users do not need to manually harvest the rewards for providing liquidity to the bridge. The bridge automatically adds rewards to the staking balance every five minutes.

Users will accrue the rewards of their liquidity provision on the destination network of a bridge migration. For example, if a user bridges from the Ethereum network to the MATIC network, a liquidity provider will receive their reward on the MATIC network.

Bridge API

Note

Connect to the Umbria Bridge API endpoint: https://bridge-api.umbria.network.

Bridge API

The bridge API can be used by developers to integrate asset migration functionality into their application. The API provides a way to query the state of current asset bridging, and a way to migrate assets via an RPC.

The bridge can operate independently of the API, due to the nature of the bridge nodes. A user can send assets to the bridge without querying the API to make sure the bridge can support the migration. If the bridge cannot support the migration, it sends the funds back to the original address, less the cost of the network fee for returning the funds. The API simply provides assurances that the asset migration will be, is being, or has been completed.

Get Number of Liquidity Providers

Get the number of liquidity providers for a particular asset on a single network

GET

Example Call:

/api/pool/getNumParticipants/?network=ethereum&tokenAddress=0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0

Example Result:

1

Get Staked

Get the unharvested rewards of an address for a particular asset on a single network

GET

Example Call:

/api/pool/getStaked/?tokenAddress=0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0&address=0xb279403e9749f2964b00eD868008eDfe84432Ff6&network=ethereum

Example Result:

0.000450977606177606

Get Harvest Nonce

Get the nonce value required to sign the transaction for removing liquidity

GET

Example Call:

/api/pool/getHarvestNonce/?tokenAddress=0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0&userAddress=0xb279403e9749f2964b00eD868008eDfe84432Ff6&network=ethereum

Example Result:

{"error":"","address":"0xEe0861faBEdc0BD4E41fe9fE97E6Cd1c7e4B717a","contractAddress":"0x2e4b0fb46a46c90cb410fe676f24e466753b469f","network":"matic","nonce":"RK7pOL59a7OazsidXiuLhBa8YckQm2JYQDHzuIZTV8MHPrUnKiTUmqlOF8Otgf9K"}

Verify Harvest Signature (Unstake)

Unstake liquidity by verifying ownership of the wallet address

GET

Example Call:

/api/pool/signUnstakeRequest/?userAddress=0xb279403e9749f2964b00eD868008eDfe84432Ff6&nonce=NpAPDiafpXtrc9RSBt1oK2hPJeCLEB99fcblkWoZXwifH5d0qJwwDAnz9clh5Uq0$signature=0x9f8a7f30aeeb402dc1858fd914be5cf47600e0d925b70b0b4b7b915bb3ab28e7326656a26aa7116ea77dd671e114255c9ee8e906946ec36ea5156cc6e5e15cbf1b

Example Result:

{"error":"","address":"0xEe0861faBEdc0BD4E41fe9fE97E6Cd1c7e4B717a","contractAddress":"0x2e4b0fb46a46c90cb410fe676f24e466753b469f","network":"matic","nonce":"RK7pOL59a7OazsidXiuLhBa8YckQm2JYQDHzuIZTV8MHPrUnKiTUmqlOF8Otgf9K"}

Get APY

Get the APY (annual percentage yield) for a particular asset on a single network

GET

Example Call:

/api/pool/getApy/?network=ethereum&currency=0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0

Example Result:

0.000000000000000000

Get APY All

Get the APY (annual percentage yield) for all assets on a single network

GET

Example Call:

/api/pool/getApyAll/?network=ethereum

Example Result:

0.000000000000000000

Get Staked

Get the volume of liquidity currently provided by an address, for a particular asset on a single network

GET

Example Call:

/api/pool/getStaked/?userAddress=0xb279403e9749f2964b00eD868008eDfe84432Ff6&tokenAddress=0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0&network=ethereum

Example Result:

{"error":"","amount":"92000000000000000","tokenAddress":"0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0","network":"ethereum"}

Get TVL All

Get the total value of locked liquidity currently provided for all assets on a single network

GET

Example Call:

/api/pool/getTvlAll/?network=ethereum

Example Result:

{"network":"ethereum","totalValue":"1398.348960000000000000","assets":{"ETH":"1398.08996","MATIC":"0.25900"},"error":""}

Get TVL

Get the total value of locked liquidity currently provided for a particular assets on a single network

GET

Example Call:

/api/pool/getTvl/?tokenAddress=0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0&network=ethereum

Example Result:

{"error":"","network":"ethereum","totalLiquidity":"0.259000000000000000"}

Get Availability

Check the availability of the api

GET

Example Call:

/api/getAvailability/?

Example Result:

{"maintenance":0,"error":""}

Get Transaction Info

Get the currenct status of a Narni Bridge transaction

GET

Example Call:

/api/bridge/getTransactionInfo/?txhash=0xb84d2de18df3f41a5a4c7fdf623e2fbdd1069763b55706399b919c67f3b4bb44

Example Result:

{"blockhash":"0xfed3c1cb75d2691f283fd7b0249ac12345ffa5b2b5c7d87e32d7934ddafba9af","bridgetxhash":"","fromaddress":"0x24e23ce29510A4Ef1bf1783A7aC8e1de2FaD38F3","amount":"1000000000000000000","asset":"umbria","asset_sent":1,"error":""}

Get Available Liquidity All

Get the amount of liquidity available for a single transaction in each asset on each network

GET

Example Call:

/api/bridge/getAvailableLiquidityAll/?

Example Result:

[{"name":"ethereum","contractAddress":"0xETH","totalLiquidity":"2223400000000000","network":"ethereum"},{"name":"matic","contractAddress":"0xMATIC","totalLiquidity":"10000000000000000","network":"matic"},{"name":"umbria","contractAddress":"0xa4bBE66f151B22B167127c770016b15fF97Dd35C","totalLiquidity":"8500000000000000000","network":"ethereum"},{"name":"matic","contractAddress":"0x7D1AfA7B718fb893dB30A3aBc0Cfc608AaCfeBB0","totalLiquidity":"47208000000000000000","network":"ethereum"},{"name":"umbria","contractAddress":"0x2e4b0Fb46a46C90CB410FE676f24E466753B469f","totalLiquidity":"18987700000000000000","network":"matic"}]

Get Available Liquidity

Get the amount of liquidity available for a single transaction in each asset on each network

GET

Example Call:

/api/bridge/getAvailableLiquidity/?network=matic&currency=0xMATIC

Example Result:

{"name":"matic","totalLiquidity":"159000000000000000"}

Get Network Fee

Get the network fee cost for the bridge transaction

GET

Example Call:

/api/bridge/getGasPrice/?network=ethereum

Example Result:

{"gasPrice":"0.000000026000000000","txPrice":"0.000546000000000000","error":"","network":"ethereum"}