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 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 60% 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, while still maintaining the cryptographic assurances of an oracle.

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, the liquidity providers of that asset receive their share of a 0.2% fee. Those who stake the UMBR token in the pool, receive their share of a 0.3% bridge 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.

Users can send their liquidity to the Narni bridge through the website, or send the funds directly to the appropriate Liquidity Address. Each liquidity address represents the liquidity pools for each bridge.

  • Ethereum/Matic bridge pool: 0x18C6f86ee9f099DeFe10b4201e48B2eF53BeAbd0
  • Ethereum/Binance Smart Chain bridge pool: 0x862F84A7cD54c8EDF1aFc98a7a676B1eA6A27Df5

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 USDC USDT WBTC GHST
polygon logo POLYGON MAINNET
ethereum logo ETHEREUM MAINNET
binance smart chain logo BINANCE SMART CHAIN
avalanche logo AVALANCE
fantom logo FANTOM
arbitrum logo ARBITRUM
optimism logo OPTIMISM
solana logo SOLANA This bridge is being deployed in Q3/Q4 of 2022
solana logo CARDANO This bridge is being deployed in Q3/Q4 of 2022
immutable x logo IMMUTABLE X This bridge is being deployed in Q3/Q4 of 2022
wax worldwide asset exchange logo WORLDWIDE ASSET EXCHANGE This bridge is being deployed in Q3/Q4 of 2022
gnosis xdai logo GNOSIS (XDAI) This bridge is being deployed in Q3/Q4 of 2022
kucoin community chain logo KUCOIN COMMUNITY CHAIN This bridge is being deployed in Q3/Q4 of 2022
huobi eco chain logo HUOBI ECO-CHAIN This bridge is being deployed in Q3/Q4 of 2022

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

Bridge Pool

Note

UMBR liquidity providers earn 60% of all fees generated on the Umbria Narni Bridge.

Users can provide asset liquidity to the Narni Bridge Pool, and earn high interest on their assets whenever someone bridges between cryptocurrency networks. The bridge uses liquidity supplied by liquidity providers to facilitate asset migration (bridging) across networks. Whenever bridging occurs, liquidity providers earn their share of a 0.2% bridging fee, while liquidity providers of the UMBR token earn their share of a 0.3% bridging fee. Liquidity providers can provide a single asset to the bridge, and earn interest in the asset they supplied. Stakers of UMBR tokens earn interest in all of the assets supported by the bridge.

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 and UMBR stakers.

The Umbria bridge pool is a no-impermanent-loss pool; liquidity providers do not lose part of the up-side if the value of the staked assets increase.

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 Widget V2

Note

The Bridge Widget V2 enables partners of Umbria to earn 0.1% of all bridging volume that comes through their widget.

Bridge Widget V2

The Bridge Widget V2 is an integratable cross-chain bridge widget. It enables projects to seamlessly provide bridging functionality, from within that project's website and UX flow. The Bridge V2 widget also generates revenue for its integrators by awarding them 0.1% of all bridging volume that passes through their bridge widget. The bridge widget is designed to be as easy as possible to integrate, so integration is as simple as adding an HTML <iframe> tag to web page, with some optional configuration parameters in the src attribute URL.

The Bridge Widget V2 supports all bridges that are currently deployed by Umbria, and is configurable, such that a pre-selected bridge and asset can be set when the user lands on the page. Much like other Umbria bridge formats, the bridge widget can be used with Metamask, or by requesting a QR code, to which funds can be sent - initiating the bridging process.

How to Integrate

Bridge Widget V2 refferer ids are given to projects on an ad hoc basis. You will need to apply to partner via the form and a member of the Umbria team will promptly reach out to you.

The Bridge Widget V2 can be added using a simple html <iframe>.

Note that the iframe must be served on a website that uses https, otherwise most browsers will block it due to mixed content rules.

<iframe src="https://umbria.network/widgetv2/?ref=REFFERER_ID" width="960" height="600" scrolling="no"></iframe>

There are a couple of configuration options that can be added to the src attribute of the <iframe> to automatically select the bridge and the asset, when the user lands on the page:

How to Pre-Select a Bridge

The bridge widget can be pre-configured to select a specific bridge when the user lands on the page. This is to remove extra steps for the user. It is configrued by adding a GET parameter on the end of the src attribute. The value of that attribute is based on which network the user should start and end on.

Below are a list of options:

Start Network End Network Entire URL
Ethereum Polygon https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic
Ethereum Binance Smart Chain https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethbsc
Ethereum Avalanche https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethavax
Ethereum Fantom https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethftm
Ethereum Arbitrum https://umbria.network/widgetv2/?ref=REFERRER_ID&route=etharb
Start Network End Network Entire URL
Polygon Ethereum https://umbria.network/widgetv2/?ref=REFERRER_ID&route=maticeth
Binance Smart Chain Ethereum https://umbria.network/widgetv2/?ref=REFERRER_ID&route=bsceth
Avalanche Ethereum https://umbria.network/widgetv2/?ref=REFERRER_ID&route=avaxeth
Fantom Ethereum https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ftmeth
Arbitrum Ethereum https://umbria.network/widgetv2/?ref=REFERRER_ID&route=arbeth

How to Pre-Select an Asset

The bridge widget can be pre-configured to select a specific asset when the user lands on the page. This is to remove extra steps for the user. For an asset to be pre-configured, a specific bridge must also be specified. Some bridges do not support some assets, so it is necessary to specify both the bridge and the asset together.

Asset GET parameter Example
Ethereum / Wrapped Ethereum (ETH / WETH) eth https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic&asset=eth
USD Coin (USDC) usdc https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic&asset=usdc
Tether (USDT) usdt https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic&asset=usdt
Polygon (MATIC) matic https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic&asset=matic
Umbria Governance Token (UMBR) umbr https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic&asset=umbr
Aavegotchi Token (GHST) ghst https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic&asset=ghst
Wrapped Bitcoin (WBTC) wbtc https://umbria.network/widgetv2/?ref=REFERRER_ID&route=ethmatic&asset=wbtc

Dashboard

The Bridge Widget V2 dashboard is available to those who have integrated the bridge widget in their website. It can be used to track earnings and other metrics through their bridge widget. To access the dashboard, you must already have received your referrer id, otherwise you will be unable to connect to the dashboard.

To open the dashboard, connect to the page via the metamask wallet which you specified during the referrer id creation process.

Reward Scheme

You are rewarded immediately every time someone uses your bridge widget to bridge assets between networks. The earnings are paid in the asset which is used to bridge. For example, if someone bridges USDC from Ethereum to Polygon, you are paid in USDC on the Polygon network.

The earnings are added to your staking balance in the pool page. This is so your bridge widget rewards earn even more APY over time, by acting as liquidity in the system, until you are ready to redeem them. To redeem your earnings, press the Unstake button of the chosen asset, on the chosen network in the pool page

You can see an itemised breakdown of your earnings in the dashboard page.

Example:

Total Earnings

Currency Earnings $$$
ETH 2.02000050 ETH $4040.00 USD
USDC 766.00495717 USDC $766.00 USD
USDT 89.12955620 USDT $89.13 USD
MATIC 1080.88840022 MATIC $1377.92 USD
UMBR 129.17772393 UMBR $492.70 USD
GHST 12.11111000 GHST $30.40 USD
wBTC 0.01339229 wBTC $407.49 USD

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.

Note: Native assets (such as Ether on the Ethereum blockchain) do not have a contractAddress/tokenAddress. For API consistency, you can reference to Ether as 0xETH, Matic as 0xMATIC, BNB as 0xBNB etc.

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&userAddress=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 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 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=0x0d952f349e5e710065a6d3e50ae4172e8291b4adf031540f1b6dfbd9497d984e

Example Result:

{"tokenAddress":"0xETH","blockhash":"0x288c54b29dae03f38e01cba5ccc73f6aeeb7584a5d835bf452a12388107bf2cb","bridgetxhash":"0x8cf2e57af080e6aa71da29b13266e9a90709cc58eaf112a160db5e4c7e2a8f4c","fromaddress":"0x7F61eF56Cd4D1a827C1Fee710C9df46aD7395E82","amount":"15000000000000000","asset":"ether","asset_sent":1,"time":"2022-01-07 14:44:23","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"}

Guides

Note

Here are some useful guides and tutorials to help you get the most out of Umbria

How to bridge ETH from Ethereum to Avalanche (AVAX)

How to bridge ETH from Ethereum to Polygon (MATIC)

How to bridge ETH from Polygon (MATIC) to Ethereum

How to bridge ETH from Ethereum to Binance Smart Chain (BSC)

How to bridge ETH from Binance Smart Chain (BSC) to Ethereum

How to connect MetaMask to Binance Smart Chain, Polygon, Ethereum, Avalanche — any network — easily

Cheap, Fast and Easy Bridging of ETH on Umbria Network

Cheap, Fast and Easy Bridging of MATIC (Polygon) on Umbria Network

Bridging ETH from Ethereum to Polygon; how do blockchain bridges vary?

Cheap and Fast Bridging of $USDC with Umbria Network’s Narni Bridge