Summary

The diagrams below shows the relationship between Share and Vault contracts:

• Share contracts are ERC-20 contracts that keep track of shares owned by wallets. They also accrue discount over time.
• Vaults are ERC-4626 contracts implemented as multi-share extensions (ERC-7575). They interact with user assets and can have additional logic like asynchronous deposits and withdrawals (ERC-7540).
• Vaults and shares can be linked in different ways. The diagram below shows an example where different vaults accept different assets and return fungible shares. This provides flexibility to Liquidity Providers (LPs) to buy and redeem receivables using different types of assets.
  • Note: Fiat can be used for deposits and withdrawals. Transfers are handled off-chain and balances recorded in an ERC-20 contract controlled by Sivo. That contract can be use as an asset by vaults.

---
config:
  theme: redux
---
flowchart TD
  %% US USDC Pool
  subgraph USA
    sUSUSD["Share: Sivo US USD 🇺🇸"]
    vUSDC["Vault US USDC"]
    vUSDT["Vault US USDT"]
    vUSDS["Vault US USD Fiat"]
    Queue[/"Queue"\]
  end

  %% Relationships
  %% Deposits from Vaults flow into Share, and Share deploys funds to Vaults
  vUSDC -->|deposits USDC| sUSUSD
  vUSDC -->|request deposit| Queue
  Queue -->|deposits USDC| sUSUSD
  vUSDT -->|deposits USDT| sUSUSD
  vUSDS -->|deposits USD Fiat| sUSUSD

• Another approach has vaults with dedicated shares. LPs can deposit and withdraw a single type of asset to each vault. Since shares are separate, they can potentially have different discount rates and liquidity constraints like max deposits.

---
config:
  theme: redux
---
flowchart TD
  subgraph Mexico
    vMXMXNT["Vault: MXMXNT"]
    sMXMXNT["Share: Sivo MX MXNT 🇲🇽"]
    vMXMXNB["Vault: MXNB"]
    sMXMXNB["Share: Sivo MX MXNB 🇲🇽"]

    vMXMXNT -->|deposits MXNT| sMXMXNT
    vMXMXNB -->|deposits MXNB| sMXMXNB
  end

• One final example has vaults for the same asset but different markets. LPs contribute the same asset and can select the type of receivables that they buy.

---
config:
  theme: redux
---
flowchart TD
  subgraph Europe
    vESEURC["Vault: ESEURC"]
    sESEURC["Share: Sivo ES EURC 🇪🇸"]
    vFREURC["Vault: FREURC"]
    sFREURC["Share: Sivo FR EURC 🇫🇷"]
    vDEEURC["Vault: DEEURC"]
    sDEEURC["Share: Sivo DE EURC 🇩🇪"]

    vESEURC -->|deposits EURC| sESEURC
    vFREURC -->|deposits EURC| sFREURC
    vDEEURC -->|deposits EURC| sDEEURC
  end

IVault

This interface defines the functions and events of the Vault contract, which manages the tokenization of receivables. As receivables become available the can be purchased with a stablecoin like USDC, USDT, EURC, etc. The contract is ERC-4626 compliant. The asset() function returns the asset contract address. The contract also handles redemption of receivable tokens (a.k.a. sTokens depending on the asset: sUSDC, sUSDT, sEURC, etc.). Pricing increases dynamically based on the amount of receivables that are sold.

VaultDeployAsset

event VaultDeployAsset(address to, uint256 assets)

Emitted when assets are deployed to RWAs

Parameters

VaultRecallAsset

event VaultRecallAsset(address from, uint256 assets)

Emitted when assets are recalled from RWAs

Parameters

IERC7575

Extended ERC-4626 Interface enabling Multi-Asset Vaults

According to ERC-7575 specification:https://eips.ethereum.org/EIPS/eip-7575
All ERC-7575 Vaults MUST implement ERC-4626 excluding the ERC-20 methods and events From @openzeppelin/contracts/interfaces/IERC4626.sol, minus ERC-20

Deposit

event Deposit(address sender, address owner, uint256 assets, uint256 shares)

Withdraw

event Withdraw(address sender, address receiver, address owner, uint256 assets, uint256 shares)

ERC7575AssetDecimalsExceedsShareDecimals

error ERC7575AssetDecimalsExceedsShareDecimals(uint8 assetDecimals, uint8 shareDecimals)

ERC7575ExceededMaxDeposit

error ERC7575ExceededMaxDeposit(address receiver, uint256 assets, uint256 max)

Attempted to deposit more assets than the max amount forreceiver.

ERC7575ExceededMaxMint

error ERC7575ExceededMaxMint(address receiver, uint256 shares, uint256 max)

Attempted to mint more shares than the max amount forreceiver.

ERC7575ExceededMaxWithdraw

error ERC7575ExceededMaxWithdraw(address owner, uint256 assets, uint256 max)

Attempted to withdraw more assets than the max amount forreceiver.

ERC7575ExceededMaxRedeem

error ERC7575ExceededMaxRedeem(address owner, uint256 shares, uint256 max)

Attempted to redeem more shares than the max amount forreceiver.

share

function share() external view returns (address shareTokenAddress)

The address of the underlying share received on deposit into the Vault

_MUST return an address of an ERC-20 share representation of the Vault
share MAY return the address of the Vault itself (i.e., share == address(this)) If share != address(this):

• entry functions MUST increase the share balance of the receiver: share.balanceOf(receiver) += shares
• exit functions MUST decrease the share balance of the owner: share.balanceOf(owner) -= shares
  MUST NOT revert_

Return Values

asset

function asset() external view returns (address assetTokenAddress)

_Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.

• MUST be an ERC-20 token contract.
• MUST NOT revert._

totalAssets

function totalAssets() external view returns (uint256 totalManagedAssets)

_Returns the total amount of the underlying asset that is “managed” by Vault.

• SHOULD include any compounding that occurs from yield.
• MUST be inclusive of any fees that are charged against assets in the Vault.
• MUST NOT revert._

convertToShares

function convertToShares(uint256 assets) external view returns (uint256 shares)

_Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
scenario where all the conditions are met.

• MUST NOT be inclusive of any fees that are charged against assets in the Vault.
• MUST NOT show any variations depending on the caller.
• MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
• MUST NOT revert.

NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and from._

convertToAssets

function convertToAssets(uint256 shares) external view returns (uint256 assets)

_Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
scenario where all the conditions are met.

• MUST NOT be inclusive of any fees that are charged against assets in the Vault.
• MUST NOT show any variations depending on the caller.
• MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
• MUST NOT revert.

NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
“average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and from._

maxDeposit

function maxDeposit(address receiver) external view returns (uint256 maxAssets)

_Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
through a deposit call.

• MUST return a limited value if receiver is subject to some deposit limit.
• MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
• MUST NOT revert._

previewDeposit

function previewDeposit(uint256 assets) external view returns (uint256 shares)

_Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
current on-chain conditions.

• MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
  call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called in the same transaction.
• MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
  deposit would be accepted, regardless if the user has enough tokens approved, etc.
• MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
• MUST NOT revert.

NOTE: any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
share price or some other type of condition, meaning the depositor will lose assets by depositing._

deposit

function deposit(uint256 assets, address receiver) external returns (uint256 shares)

_Mints shares Vault shares to receiver by depositing exactly amount of underlying tokens.

• MUST emit the Deposit event.
• MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
  deposit execution, and are accounted for during deposit.
• MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
  approving enough underlying tokens to the Vault contract, etc).

NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token._

maxMint

function maxMint(address receiver) external view returns (uint256 maxShares)

_Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call.

• MUST return a limited value if receiver is subject to some mint limit.
• MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
• MUST NOT revert._

previewMint

function previewMint(uint256 shares) external view returns (uint256 assets)

_Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
current on-chain conditions.

• MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
  in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the same transaction.
• MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
  would be accepted, regardless if the user has enough tokens approved, etc.
• MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
• MUST NOT revert.

NOTE: any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
share price or some other type of condition, meaning the depositor will lose assets by minting._

mint

function mint(uint256 shares, address receiver) external returns (uint256 assets)

_Mints exactly shares Vault shares to receiver by depositing amount of underlying tokens.

• MUST emit the Deposit event.
• MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
  execution, and are accounted for during mint.
• MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
  approving enough underlying tokens to the Vault contract, etc).

NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token._

maxWithdraw

function maxWithdraw(address owner) external view returns (uint256 maxAssets)

_Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
Vault, through a withdraw call.

• MUST return a limited value if owner is subject to some withdrawal limit or timelock.
• MUST NOT revert._

previewWithdraw

function previewWithdraw(uint256 assets) external view returns (uint256 shares)

_Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
given current on-chain conditions.

• MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
  call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if called in the same transaction.
• MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
  the withdrawal would be accepted, regardless if the user has enough shares, etc.
• MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
• MUST NOT revert.

NOTE: any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
share price or some other type of condition, meaning the depositor will lose assets by depositing._

withdraw

function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares)

_Burns shares from owner and sends exactly assets of underlying tokens to receiver.

• MUST emit the Withdraw event.
• MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
  withdraw execution, and are accounted for during withdraw.
• MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
  not having enough shares, etc).

Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
Those methods should be performed separately._

maxRedeem

function maxRedeem(address owner) external view returns (uint256 maxShares)

_Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
through a redeem call.

• MUST return a limited value if owner is subject to some withdrawal limit or timelock.
• MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
• MUST NOT revert._

previewRedeem

function previewRedeem(uint256 shares) external view returns (uint256 assets)

_Allows an on-chain or off-chain user to simulate the effects of their redemption at the current block,
given current on-chain conditions.

• MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
  in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the same transaction.
• MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
  redemption would be accepted, regardless if the user has enough shares, etc.
• MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
• MUST NOT revert.

NOTE: any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
share price or some other type of condition, meaning the depositor will lose assets by redeeming._

redeem

function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets)

_Burns exactly shares from owner and sends assets of underlying tokens to receiver.

• MUST emit the Withdraw event.
• MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
  redeem execution, and are accounted for during redeem.
• MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
  not having enough shares, etc).

NOTE: some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
Those methods should be performed separately._

IERC7540Operator

Interface for managing operator permissions for ERC-7540 compatible vaults

Allows controllers to designate operators who can act on their behalf

OperatorSet

event OperatorSet(address controller, address operator, bool approved)

isOperator

function isOperator(address controller, address operator) external view returns (bool status)

_Returns true if operator is approved to manage requests on behalf of controller

• MUST NOT revert._

Parameters

Return Values

setOperator

function setOperator(address operator, bool approved) external returns (bool success)

_Grant or revoke operator permissions for msg.sender (the controller)

• MUST emit the OperatorSet event.
• MUST return true on success._

Parameters

Return Values

IERC7540Deposit

Interface for handling asynchronous deposits in ERC-7540 compatible vaults

Provides methods for requesting and claiming deposits

DepositRequest

event DepositRequest(address controller, address owner, uint256 requestId, address sender, uint256 assets)

ERC7540UnauthorizedSender

error ERC7540UnauthorizedSender(address sender, address subject)

requestDeposit

function requestDeposit(uint256 assets, address controller, address owner) external returns (uint256 requestId)

_Initiate an asynchronous deposit request, locking assets and returning a requestId

• MUST emit the DepositRequest event.
• MUST lock the assets until they can be claimed.
• MUST return a unique requestId that can be used to track and claim the deposit._

Parameters

Return Values

pendingDepositRequest

function pendingDepositRequest(uint256 requestId, address controller) external view returns (uint256 assets)

_Returns the amount of assets pending deposit for a controller under a specific requestId

• MUST NOT revert if the requestId exists.
• MUST return 0 if the requestId does not exist or if the assets are no longer pending._

Parameters

Return Values

claimableDepositRequest

function claimableDepositRequest(uint256 requestId, address controller) external view returns (uint256 assets)

_Returns the amount of assets claimable for deposit by a controller under a specific requestId

• MUST NOT revert if the requestId exists.
• MUST return 0 if the requestId does not exist or if the assets are not yet claimable._

Parameters

Return Values

deposit

function deposit(uint256 assets, address receiver, address controller) external returns (uint256 shares)

_Claims deposited assets similar to ERC-4626 deposit, but with controller parameter

• MUST emit the Deposit event.
• MUST convert the claimed assets to shares and transfer them to receiver.
• MUST revert if assets cannot be claimed._

Parameters

Return Values

mint

function mint(uint256 shares, address receiver, address controller) external returns (uint256 assets)

_Claims deposited assets via ERC-4626 mint semantics, with controller parameter

• MUST emit the Deposit event.
• MUST mint the specified shares to receiver.
• MUST revert if shares cannot be minted._

Parameters

Return Values

IERC7540Redeem

Interface for handling asynchronous redemptions in ERC-7540 compatible vaults

Provides methods for requesting and tracking redemptions
Semantics for redeem and withdraw functions: if the controller has claimable redemptions it follows async (ERC-7540) semantics and consumes claimable redemptions with pricing that was locked when the request transitioned to claimable. Otherwise it follows sync (ERC-4626) semantics that consume shares.

RedeemRequest

event RedeemRequest(address controller, address owner, uint256 requestId, address sender, uint256 assets)

requestRedeem

function requestRedeem(uint256 shares, address controller, address owner) external returns (uint256 requestId)

_Initiate an asynchronous redemption request, locking shares and returning a requestId

• MUST emit the RedeemRequest event.
• MUST lock the shares until they can be redeemed.
• MUST return a unique requestId that can be used to track the redemption._

Parameters

Return Values

pendingRedeemRequest

function pendingRedeemRequest(uint256 requestId, address controller) external view returns (uint256 shares)

_Returns the amount of shares pending redemption for a controller under a specific requestId

• MUST NOT revert if the requestId exists.
• MUST return 0 if the requestId does not exist or if the shares are no longer pending._

Parameters

Return Values

claimableRedeemRequest

function claimableRedeemRequest(uint256 requestId, address controller) external view returns (uint256 shares)

_Returns the amount of shares claimable for redemption by a controller under a specific requestId

• MUST NOT revert if the requestId exists.
• MUST return 0 if the requestId does not exist or if the shares are not yet claimable._

Parameters

Return Values

IShare

This interface defines the functions and events of the Share contract, which manages the tokenization of receivables. As receivables become available the can be purchased with a stablecoin like USDC, USDT, EURC, etc. The contract is ERC-4626 compliant. The asset() function returns the asset contract address. The contract also handles redemption of receivable tokens (a.k.a. sTokens depending on the asset: sUSDC, sUSDT, sEURC, etc.). Pricing increases dynamically based on the amount of receivables that are sold.

DiscountChange

event DiscountChange(uint256 discountRateBase, uint256 discountRateSlope)

Emitted when the discount rate parameters are updated

Parameters

IdleFactorChange

event IdleFactorChange(uint256 minIdleFactor, uint256 maxIdleFactor)

Emitted when the idle factor parameters are updated

Parameters

UpdateVault

event UpdateVault(address vault, bool isVault)

Emitted when the vault status is updated

Parameters

Accrue

event Accrue(uint256 timeElapsed, uint256 assetTotalDeployedStart, uint256 assetTotalDeployedEnd, uint256 assetTotalIdle)

Emitted when discount accrual is processed

Parameters

ShareDeployAsset

event ShareDeployAsset(address vault, uint256 assets)

Emitted when assets are deployed to RWAs

Parameters

ShareRecallAsset

event ShareRecallAsset(address vault, uint256 assets)

Emitted when assets are recalled from RWAs

Parameters

TimestampTooLarge

error TimestampTooLarge(uint256 timestamp)

Error thrown when the timestamp exceeds the maximum value that can be stored

Parameters

ShareUnauthorizedVault

error ShareUnauthorizedVault()

Error thrown when the caller is not a vault

ShareInsufficientIdleAssets

error ShareInsufficientIdleAssets(uint256 assets, uint256 max)

Error thrown when there are insufficient idle assets

Parameters

ShareInsufficientDeployedAssets

error ShareInsufficientDeployedAssets(uint256 assets, uint256 max)

Error thrown when there are insufficient deployed assets

Parameters

AccrualOutOfDate

error AccrualOutOfDate(uint256 timeElapsed)

Error thrown when the accrual is out of date

Parameters

discountRateSlope

function discountRateSlope() external view returns (uint64)

The slope component of the discount rate (per second)

Adjusted by dividing annual rate by SECONDS_PER_YEAR

discountRateBase

function discountRateBase() external view returns (uint64)

The base component of the discount rate (per second)

Adjusted by dividing annual rate by SECONDS_PER_YEAR

minIdleFactor

function minIdleFactor() external view returns (uint64)

The minimum idle factor, representing the minimum percent of total assets that must remain idle

Scaled by FactorScale (1e18)

maxIdleFactor

function maxIdleFactor() external view returns (uint64)

The maximum idle factor, representing the maximum percent of total assets that should remain idle

Scaled by FactorScale (1e18)

lastAccrualTime

function lastAccrualTime() external view returns (uint40)

The timestamp of the last accrual calculation

Stored as uint40 to save gas, can represent timestamps until year 36812

assetTotalDeployed

function assetTotalDeployed() external view returns (uint256)

Returns the total assets deployed

Calculated by applying discount accrual since last update

assetTotalIdle

function assetTotalIdle() external view returns (uint256)

Returns the total assets idle

Includes idle assets across all vaults

accrueRate

function accrueRate(uint256 utilization_) external view returns (uint256)

Calculates the accrual rate of deployed assets based on utilization

The accrual rate is used to determine how share value increases over time

Parameters

Return Values

previewAccrue

function previewAccrue() external view returns (uint256, uint256, uint256, uint256)

Simulates an accrual at the current block, given current on-chain conditions

Uses the time elapsed since last accrual and calculates accrual

Return Values

accrue

function accrue() external

Performs an accrual at the current block, given current on-chain conditions

Can only be called by the vaults. Should be called by vaults before converting between assets and shares.

mint

function mint(address to, uint256 shares, uint256 assets) external

Mints shares to the specified address

Can only be called by linked vaults

Parameters

burn

function burn(address owner, uint256 shares, uint256 assets) external

Burns shares from the specified owner

Can only be called by linked vaults

Parameters

spendAllowance

function spendAllowance(address owner, address spender, uint256 shares) external

Spends the allowance of shares from the owner to the spender

Can only be called by linked vaults

Parameters

deploy

function deploy(uint256 assets) external returns (uint256)

Deploys assets from vault to RWA

Can only be called by the contract owner
Transfers assets from contract to owner and increases the assetTotalInRwa Emits a TransferToRwa event after the transfer is complete

Parameters

Return Values

recall

function recall(uint256 assets) external returns (uint256)

Recalls assets from RWA

Can only be called by the contract owner
Transfers assets from rwa to vault and decreases the assetTotalInRwa Emits a TransferFromRwa event after the transfer is complete

Parameters

Return Values