1 of 21

Alluvial

Who is Alluvial?

Alluvial is a software development company supporting the development of the Liquid Collective protocol. We're focused on the overall growth and maturity of the ecosystem by fostering participation in proof of stake blockchains.

To learn more about the Liquid Collective protocol and how it works, check out Liquid Collective's documentation.

New to Alluvial's documentation?

The Alluvial docs have three key sections:

: This section contains several step by step guides for how technical teams can implement key Liquid Staking flows.
: This section shows all the raw API requests that Liquid Collective Platforms can call.
: This section includes guides for how to interact with the Liquid Collective protocol via other software platforms.

Helpful tips

If you are an engineer or technical person, looking to understand the level of effort or work involved in implementing the key flows (ETH staking and LsETH redemptions) then we recommend reviewing the and guides. The is a helpful compliment to these key guides.

Guides

Using Alluvial APIs makes it easy to onboard and interact with the Liquid Collective protocol.

There are two types of Liquid Collective Platforms. Platforms either:

Enable mint/redeem: These Platforms enable direct Liquid Collective protocol interactions, including depositing ETH to Ethereum's deposit contract and redeeming LsETH for ETH (minting and redeeming). These Platforms offer KYC/AML and Sanctions Screening procedures for their users, then submit the user's wallet address to Liquid Collective's Allowlist smart contract upon successful completion.

Mint and Redeem support

Pre-read

Review the Authentication Guide for the Alluvial API.

Onboarding wallets

Create an Account object

First create an account object for each of your users.

Request:

Response:

Create Wallet objects

Add wallet to Allowlist

Attach a wallet object to each account. You can add the wallet to the Allowlist (on-chain) or the On-Platform list (off-chain).

The first example below shows how to add a wallet address to the Allowlist (which be default is added to the On-Platform list).

Use the Alluvial account in UUID in the uri Path

Request:

The status of the Wallet object upon creation will be NOT_READY. This is because the wallet information will be sent to the Allowlist smart contract to update the Registry. Once the Registry contract is updated, the status will change to ALLOWLISTED.

Once the wallet address is added to the Allowlist it will also automatically be added to the On-Platform list.

Response:

Add wallet to On-Platform list

Platforms that enable mint/redeem may also need to add a wallet address to the On-Platform list separately. The following request is for a Platform that enables mint/redeem to add a wallet to the On-Platform list.

Request:

Now that you have an Account object created and Wallet objects associated, the user can stake ETH and mint LsETH. Before depositing, ensure that the Wallet object(s) have a status = ALLOWLISTED.

Stake ETH

To complete the staking process, review .

Secondary Interaction support

Pre-read

Review the Authentication Guide for the Alluvial API.

Create an Account object

Platforms that enable secondary protocol interactions, such as trading, lending, or other services, can create an Account object. The Account object is generally associated with a Platform's customer.

Request:

Response:

Create a Wallet object

After an Account object is created, associate a Wallet object to an account. You can associate one or many Wallet objects to a given Account object.

Request:

Response:

Your Platform is all set! Wallets added to the On-Platform list will be used to calculate the relevant Protocol Service Fee Rebates.

Reporting

Alluvial's reporting API enables Platforms to request the ETH network rewards that their users have received. Below are two guides:

Platforms with omnibus account structure.
Platforms with segregated account structure.

Omnibus account structure

Platforms that support an omnibus structure should use the /eth/v0/rewards endpoint. This will return data in a lots structure. Lots represent LsETH balance changes for a given period. Rewards can then be calculated for each period. Total rewards for a user is the sum of rewards for each lot.

Below is an example request where a Platform wants to see the rewards for a wallet. Assume that the user has a total balance of 3 but acquired at different dates.

The user had 1 LsETH from 2024-04-01 to 2024-04-10. As such this will be the first lot added to the request body.
The user then acquired 2 more LsETH, for a total of 3, as of 2024-04-11.

In our request below assume that the current date for which we want data is til 2024-04-15.

Request

Response

Segregated account structure

Platforms that support a segregated structure can use two different endpoints to get reward data at the account or wallet level.

List rewards by account(s)

Use the endpoint /eth/v0/rewards/accounts to display ETH network rewards at the account level.

For a range of days, use the endpoint /eth/v0/rewards/accounts/:idOrKey/summary

Request

Response

Below is the response show the aggregated rewards for the account in addition for each address.

List rewards by wallet(s)

Use the endpoint /eth/v0/rewards/wallets to display ETH network rewards at the wallet level.

For a range of days, use the endpoint /eth/v0/rewards/wallets/:idOrKey/summary

Request

Response

Below is the response showing the aggregated rewards for the account in addition for each address.

Staking Reward Rate

The Alluvial API provides a staking rewards rate (SRR), which is calculated as a 7 day trailing average.

To get SRR information, call the endpoint.

Request

Response

Based on providing a specific date of 2024-05-01, the returned SRR is 2.85%.

Discounting API

Platforms that want to provide a custom discount to their users can use the Discounting APIs to offload the calculations of a discounted net Protocol Service Fee to Alluvial's enterprise accounting service. Platforms can then use the API to call ETH network rewards, Protocol Service Fees, and end user discounts for one or more wallets or user accounts.

First, you will set a new target fee rate. This represents the new gross Protocol Service Fee rate that will be calculated for an account and/or wallet.

For example, the current gross rate is 10%. To offer a user an effective net rate of 8%, you'd set the target fee rate at 0.08, which effectively provides a 2% discount to the associated wallet(s) and/or account(s).

Request

The target fee rate is now set at 8%.

Response

On each Oracle report, you can use the Reporting APIs to see discounted values for the associated account, including the discounted net Protocol Service Fee, ETH network rewards received adjusted for that Fee, and effective end user discounts.

Request

In the response below, you can see that the rebate_eth or rebate_lseth will reflect the amount the wallet is attributed to be reimbursed in order to achieve the the 8% target fee rate (or conversely, a 2% discount on the gross Protocol Service Fee).

Response

The discount data is exposed via the following API endpoints:

/rewards/wallets
/eth/v0/rewards/accounts/:idOrKey/summary
/eth/v0/rewards/wallets/:idOrKey/summary

Supplemental Guides

Architecture

This guide is intended for Platforms to learn about how they can integrate the Liquid Collective protocol with the support of Alluvial's APIs.

To help illustrate how a Platform utilizes the Alluvial APIs to support its Liquid Collective protocol integration, this guide introduces a few fictional characters:

Acme Custodian Corp: Financial institution that is a Platform for the Liquid Collective protocol and will offer its customers the ability to participate in the Liquid Collective protocol by staking ETH.
Alice: user of Acme Custodian Corp

Authentication

This guide walks users through how to use authenticate requests using the Alluvial APIs.

Client Credentials Flow

Below is a ladder diagram showing the flow to create an access token.

This flow involves 3 parties:

APIs

Alluvial exposes several APIs to help developers interact with the Liquid Collective Protocol.

API-Reference

Authentication API

This page shows the process for creating an access token.

When onboarding with Alluvial, you will receive API credentials. These include a client_id and client_secret.
After receiving your credentials use the curl request below, updating the client_id and client_secret with your specific credentials.

Ethereum Data API

Ethereum Data API is a collection of APIs that expose read data from the Ethereum network.

Allowlisting API

Ethereum

Platform Account Operations

Redemption API

Redemption API is a collection of APIs that expose read data on redemptions.

To see APIs used in an example implementation check out the Redemption guide (below).

Reporting API

Reporting API is a collection of APIs Platforms use to get information about Liquid Collective Protocol Service Fees.

Public endpoints (no authentication required)

Discounting API

APIs that allow Platforms to create target discount schedules.

Public APIs

Alluvial exposes several non-authenticated APIs to support DApps

Third Party Integration Guides

Alluvial's APIs can also interact with other third party services, such as those offered by third party custodians that Platforms may use to custody funds staked using Liquid Collective.

Please note that these guides are to support Platforms who are connecting with third party products that are not offered by or in partnership or affiliation with Alluvial. Products and services offered by third parties are subject to separate terms and conditions. Visit the website of the third parties noted in these guides for more information on their offerings.

Changelog

Alluvial's changelog records changes made to the Alluvial API specification, including new features, improvements, bug fixes, and more.

July 9, 2024

Discounting APIs are live! These APIs enable adding a new target rate in the event Platforms need to adjust the net Protocol Service Fee rate for specific accounts and/or wallets.

curl -X 'POST' \
  'https://api.staging.alluvial.finance/v0/platform/accounts/da36a6fa-070d-4cd1-b99a-f2da4f4ccb20/wallets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGci…CVm5g' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": "0x5210d328bC5651F92F4557EfDE08dd97A36A935c",
  "type": "ETH"
}'

{
  "id": "a41c520e-fadd-4c0c-a1ce-d574ee731cee",
  "type": "ETH",
  "address": "0x5210d328bC5651F92F4557EfDE08dd97A36A935c",
  "account_id": "993327a3-1d48-4eff-a9ee-7ec769ec1f64",
  "status": "ALLOWLISTED",
  "allowlisted": true,
  "on_platform": true,
  "created_at": "2024-03-25T18:38:31.427654433Z"
}

curl -X 'POST' \
  'https://api.staging.alluvial.finance/v0/platform/accounts/da36a6fa-070d-4cd1-b99a-f2da4f4ccb20/wallets' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGci…CVm5g' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": "0x5210d328bC5651F92F4557EfDE08dd97A36A935c",
  "type": "ETH",
  "allowlisted": "false"
}'

curl -X 'POST' \
  'https://api.staging.alluvial.finance/v0/platform/accounts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGci…CVm5g' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "FO123"
}'

{
  "id": "4b1d05ed-b498-4847-99a0-c415c6b19f6b",
  "key": "foobar-123",
  "org_id": "org_WaYHN06ay6WoT...",
  "status": "ACTIVE",
  "created_at": "2024-02-09T22:40:28.954304245Z",
  "wallets": []
}

curl -X 'POST' \
  'https://api.staging.alluvial.finance/v0/platform/accounts/4b1d05ed-b498-4847-99a0-c415c6b19f6b/wallets/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 'eyJhbGci…CVm5g'
  -D '{
 "address": "0x469b998812B9675b7B2Fb37519f574fEA5ee92E8",
 "allowlisted": "false",
 "type": "ETH"
}'

{
  "id": "421a39a1-e9c3-4a33-81bc-98eff7bfd502",
  "type": "ETH",
  "address": "0x469b998812b9675b7b2fb37519f574fea5ee92e8",
  "status": "NOT_ALLOWLISTED",
  "on_platform": true,
  "created_at": "2024-02-09T22:43:02.249045841Z"
}

curl -X 'POST' \
  'https://auth.staging.alluvial.finance/oauth/token' \
  -H 'content-type: application/json' \
  -d '{
    "audience": "https://api.staging.alluvial.finance",
  "grant_type": "client_credentials",
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>"
}'

curl -X 'POST' \
  'https://auth.alluvial.finance/oauth/token' \
  -H 'content-type: application/json' \
  -d '{
    "audience": "https://api.alluvial.finance",
  "grant_type": "client_credentials",
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>"
}'

curl  'https://auth.alluvial.finance/oauth/token' \
--header 'content-type: application/json' \
--data '{
 "audience": "https://api.staging.alluvial.finance",
 "grant_type": "client_credentials",
 "client_id": "<YOUR_CLIENT_ID>",
 "client_secret": "<YOUR_CLIENT_SECRET>"
}'

[
  {
    "claimable_amount_lseth": 1,
    "claimed_amount_eth": 1,
    "claimed_amount_lseth": 1,
    "height": 1,
    "id": 1,
    "max_redeemable_amount_eth": 1,
    "owner": [
      1
    ],
    "requested_at": 1,
    "status_claim": "NOT_CLAIMED",
    "status_satisfaction": "NOT_CLAIMED",
    "timestamp": "text",
    "total_amount_lseth": 1,
    "withdrawal_event_id": 1
  }
]

{
  "claimable_amount_lseth": 1,
  "claimed_amount_eth": 1,
  "claimed_amount_lseth": 1,
  "height": 1,
  "id": 1,
  "max_redeemable_amount_eth": 1,
  "owner": [
    1
  ],
  "requested_at": 1,
  "status_claim": "NOT_CLAIMED",
  "status_satisfaction": "NOT_CLAIMED",
  "timestamp": "text",
  "total_amount_lseth": 1,
  "withdrawal_event_id": 1
}

curl --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer e...g' \
--data '[
	{
		"balance": "1",
		"from": "2024-04-01",
		"to": "2024-04-10"
	},
	{
		"balance": "3",
		"from": "2024-04-11",
		"to": "2024-04-15"
	}
]'

{
  "balance": "4",
  "accrued_rewards": "0.0041516089956458",
  "lots": [
    {
      "from": "2024-04-01",
      "to": "2024-04-10",
      "start_conversion_rate": "1.0014257204933798",
      "end_conversion_rate": "1.0023467329617235",
      "balance": "1",
      "accrued_rewards": "0.0009210124683437"
    },
    {
      "from": "2024-04-11",
      "to": "2024-04-15",
      "start_conversion_rate": "1.0026157619809285",
      "end_conversion_rate": "1.0036926274900292",
      "balance": "3",
      "accrued_rewards": "0.0032305965273021"
    }
  ]
}

curl --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards/accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Impersonate-Org: org_uLD0aCAXyWYg4WQH' \
--header 'Authorization: Bearer ey...Qg' \
--data '{
	"accounts": [
		"8f9d6eff-d630-4389-810f-89c4b07b8fc5"
	],
	"date": "2024-05-15",
	"unit": "eth"
}'

[
  {
    "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
    "totals": {
      "balance_lseth": "0.0000198315414745",
      "rewards_eth": "0.000000000092766089"
    },
    "date": "2024-05-15",
    "wallets": [
      {
        "oracle_report": "1437a7330f02400a5662ed70f5c23b251d76fdb1ede48240d9f1e7bcd70540470000014b",
        "address": "0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A",
        "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
        "org_id": "org_WaYHN06ay6WoTjcz",
        "date": "2024-05-15",
        "balance_lseth": "0.00000991577073725",
        "rewards_eth": "0.000000000092766089",
        "total_rewards_eth": "0.000000000092766089",
        "conversion_rate": "1.0085131998588114",
        "previous_conversion_rate": "1.0085038444500037",
        "mints_lseth": "0",
        "total_mints_lseth": "0.00000991577073725",
        "burns_lseth": "0",
        "total_burns_lseth": "0",
        "fees_eth": "0.000000000010307343",
        "total_fees_eth": "0.000000000010307343",
        "dao_fees_eth": "0.000000000000979198",
        "total_dao_fees_eth": "0.000000000000979198",
        "provider_fees_eth": "0.000000000000360757",
        "total_provider_fees_eth": "0.000000000000360757",
        "slashing_fees_eth": "0.00000000000030922",
        "total_slashing_fees_eth": "0.00000000000030922",
        "platform_fees_eth": "0.000000000007112067",
        "total_platform_fees_eth": "0.000000000007112067",
        "operator_fees_eth": "0.000000000001546101",
        "total_operator_fees_eth": "0.000000000001546101"
      }
    ]
  }
]

curl --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards/wallets' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Impersonate-Org: org_uLD0aCAXyWYg4WQH' \
--header 'Authorization: Bearer ey...Qg' \
--data '{
	"addresses": [
		"0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A"
	],
	"date": "2024-05-15",
	"unit": "eth"
}'

[
  {
    "oracle_report": "1437a7330f02400a5662ed70f5c23b251d76fdb1ede48240d9f1e7bcd70540470000014b",
    "address": "0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A",
    "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
    "org_id": "org_WaYHN06ay6WoTjcz",
    "date": "2024-05-15",
    "balance_lseth": "0.00000991577073725",
    "rewards_eth": "0.000000000092766089",
    "total_rewards_eth": "0.000000000092766089",
    "conversion_rate": "1.0085131998588114",
    "previous_conversion_rate": "1.0085038444500037",
    "mints_lseth": "0",
    "total_mints_lseth": "0.00000991577073725",
    "burns_lseth": "0",
    "total_burns_lseth": "0",
    "fees_eth": "0.000000000010307343",
    "total_fees_eth": "0.000000000010307343",
    "dao_fees_eth": "0.000000000000979198",
    "total_dao_fees_eth": "0.000000000000979198",
    "provider_fees_eth": "0.000000000000360757",
    "total_provider_fees_eth": "0.000000000000360757",
    "slashing_fees_eth": "0.00000000000030922",
    "total_slashing_fees_eth": "0.00000000000030922",
    "platform_fees_eth": "0.000000000007112067",
    "total_platform_fees_eth": "0.000000000007112067",
    "operator_fees_eth": "0.000000000001546101",
    "total_operator_fees_eth": "0.000000000001546101"
  }
]

[
  {
    "oracle_report": "2e39c7e7e0b78c043ac98e190175fa7f057a75197647d4d844864ac06c98aa3400000225",
    "date": "2024-05-01T12:14:47Z",
    "total_protocol_mints_lseth": "89180.704128270784037675",
    "total_protocol_burns_lseth": "6676.332903830493099868",
    "total_protocol_active_keys_count": 2703,
    "rewards_eth": "6.66289490787142415",
    "gross_fee_rate": "0.1",
    "gross_fee_lseth": "0.636483355669561459",
    "conversion_rate": "1.0468294022963504",
    "total_lseth_supply": "82674.954629966742503924",
    "a_srr_7d": "2.85"
  }
]

curl --location --request POST 'https://api.staging.alluvial.finance/v0/platform/accounts/8f9d6eff-d630-4389-810f-89c4b07b8fc5/discount_rate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJQ' \
--data '{
  "target_fee_rate": 0.08
}'

curl --location --request POST 'https://api.staging.alluvial.finance/eth/v0/rewards/accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ...mQ' \
--data '{
  "accounts": [
    "8f9d6eff-d630-4389-810f-89c4b07b8fc5"
  ],
  "date": "2024-06-22",
  "unit": "lseth"
}'

[
  {
    "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
    "totals": {
      "balance_lseth": "0.947997263286356641",
      "rewards_eth": "0.001671038079957103"
    },
    "date": "2024-06-22",
    "wallets": [
      {
        "oracle_report": "43306f4695a1d7ed4118c68fecd150e1f071b338815007960e61900d8d9c123e00000046",
        "address": "0x4D1c3ec0B381F012A90f096cD4E8bc7746e4f2eB",
        "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
        "org_id": "org_WaYHN06ay6WoTjcz",
        "date": "2024-06-22",
        "balance_lseth": "0.00001",
        "rewards_eth": "0.000000000087955639",
        "total_rewards_eth": "0.000000020987954327",
        "conversion_rate": "1.0106749980064223",
        "previous_conversion_rate": "1.0106662024425232",
        "mints_lseth": "0",
        "total_mints_lseth": "0",
        "burns_lseth": "0",
        "total_burns_lseth": "0",
        "fees_eth": "0.000000000009772849",
        "total_fees_eth": "0.000000002331994927",
        "dao_fees_eth": "0.000000000000928421",
        "total_dao_fees_eth": "0.000000000221539524",
        "provider_fees_eth": "0.00000000000034205",
        "total_provider_fees_eth": "0.000000000081619819",
        "slashing_fees_eth": "0.000000000000293185",
        "total_slashing_fees_eth": "0.00000000006995985",
        "platform_fees_eth": "0.000000000006743266",
        "total_platform_fees_eth": "0.000000001609076496",
        "platform_fees_at_discount_rate_eth": "0",
        "total_platform_fees_at_discount_rate_eth": "0",
        "operator_fees_eth": "0.000000000001465927",
        "total_operator_fees_eth": "0.00000000034979924",
        "gross_protocol_fee_rate": "0",
        "discount_rate": "0",
        "gross_fees_eth": "0.000000000009772849",
        "total_gross_fees_eth": "0.000000002331994927",
        "gross_rewards_eth": "0.000000000097728488",
        "total_gross_rewards_eth": "0.000000000189971905",
        "rebate_eth": "0",
        "total_rebate_eth": "0",
        "rebate_lseth": "0",
        "total_rebate_lseth": "0"
      },
      {
        "oracle_report": "43306f4695a1d7ed4118c68fecd150e1f071b338815007960e61900d8d9c123e00000046",
        "address": "0x7fc2B172EcC8E4609088f341Aa0Fb3841De8A77A",
        "account_id": "8f9d6eff-d630-4389-810f-89c4b07b8fc5",
        "org_id": "org_WaYHN06ay6WoTjcz",
        "date": "2024-06-22",
        "balance_lseth": "0.947987263286356641",
        "rewards_eth": "0.000008338082549768",
        "total_rewards_eth": "0.001671017092002776",
        "conversion_rate": "1.0106749980064223",
        "previous_conversion_rate": "1.0106662024425232",
        "mints_lseth": "0",
        "total_mints_lseth": "5.947997863289656641",
        "burns_lseth": "0",
        "total_burns_lseth": "0.0000006000033",
        "fees_eth": "0.000000926453616641",
        "total_fees_eth": "0.000185668565778085",
        "dao_fees_eth": "0.000000088013093581",
        "total_dao_fees_eth": "0.000017638513748923",
        "provider_fees_eth": "0.000000032425876582",
        "total_provider_fees_eth": "0.000006498399802232",
        "slashing_fees_eth": "0.000000027793608499",
        "total_slashing_fees_eth": "0.000005570056973343",
        "platform_fees_eth": "0.000000639252995482",
        "total_platform_fees_eth": "0.000128111310386881",
        "platform_fees_at_discount_rate_eth": "0",
        "total_platform_fees_at_discount_rate_eth": "0",
        "operator_fees_eth": "0.000000138968042496",
        "total_operator_fees_eth": "0.000027850284866709",
        "gross_protocol_fee_rate": "0",
        "discount_rate": "0",
        "gross_fees_eth": "0.000000926453616641",
        "total_gross_fees_eth": "0.000185668565778085",
        "gross_rewards_eth": "0.000009264536166409",
        "total_gross_rewards_eth": "0.000018009094566287",
        "rebate_eth": "0",
        "total_rebate_eth": "0",
        "rebate_lseth": "0",
        "total_rebate_lseth": "0"
      }
    ]
  }
]

Redemptions

Goals

This guide is a technical guide with examples of how to implement Liquid Collective’s redemption workflow into a Platform's workflow. For more information on Liquid Collective’s ETH staking withdrawal architecture, check out Liquid Collective’s LsETH redemption documentation

Pre-read

Review the for the Alluvial API.

Implementation

The guide will using the Hoodi network for smart contract calls.

For this example, the implementation will use both smart contract calls and offchain calls via the Redemption API.

The Redemption API is an offchain API that exposes:

The list of redeem requests for an owner (wallet) including their redemption IDs
The status information about redeem requests (including id, redeemed amount, satisfaction status, claim status, etc.)
The heights of the withdrawal stack (ETH supplied) and the redeem queue (LsETH queued to redeem). Learn more on different queues & stacks.

For Contract Addresses: view this . Make sure you use the Contract Address when sending txs.

For ABIs: This guide uses Hoodi testnet and interacts with two contracts: and . RedeemManger contract is only needed if listening to RedeemManager contract events.

Create Redemption Request

The LsETH contract exposes a function called .

As an Platform, you allow users to submit (or to request that you submit on their behalf) the amount of LsETH they wish to redeem.

Note: In some cases, the recipient may be different from the message sender. For example: if using an omnibus model, you may have LsETH in a wallet separate from the user’s ETH wallet. In this case, the LsETH wallet will make the requestRedeem, however, the recipient of ETH will be the ETH wallet.

After successfully calling requestRedeem function an ID will be generated. Keep this redeemRequestId as you will use it later on.

Below is a code snippet that will call the requestRedeem function.

Code uses public RPC as its provider to interact with smart contracts and uses Ethers.js

Contract.json is the ABI associated with the LsETH contract

RequestedRedeem event

When creating a requestRedeem, the LsETH contract will emit a RequestedRedeem event. The event contains the redeem request IDs. Additionally, you can use the Redemption API to retrieve redeem request IDs associated with an owner, which is demonstrated later on in this guide.

Below is a code snippet for listening to the RequestedRedeem event via websocket connection.

Request:

Code uses public RPC as its provider to interact with smart contracts and uses Ethers.js

Contract.json is the ABI associated with the LsETH contract

run in terminal

Response:

As you can see in the response below, the redeem request ID is 18. This is the request ID associated with the request earlier in the “Create Redeem Request” section of this guide.

The full lifecycle method visual can be seen .

eth/v0/redeems

You can use the Redemption API to list the redeemRequests for a given recipient wallet.

You can get a list of all redemptions associated with a wallet using the curl request below.

Request

Response:

You can see information related to the status of the redemption. Later on, you will see the status update as the redeemRequest becomes satisfied and can be claimed.

For all status combinations check out this

Timing projections

Now that you have a redeem ID, use the projections endpoint to get an estimate of how long it might take for the redeemRequest to be satisfied and become claimable.

Request:

Response:

The response below displays when the redeemRequest is likely to be redeemable. Once redeemable, you can use resolveRedeemRequests to get the matching withdrawal event ID.

Reported withdrawal event

A withdrawal event is triggered at the time of the protocol’s Oracle report. Oracles report every 24 hours.

Withdrawal event IDs are not generated instantly, even if there is enough supply. Withdrawal event IDs will be generated at the next Oracle report after redeem request is submitted. This is by design to ensure a fair redemption process for all Liquid Collective participants.

Below is an example event.

Request:

This event will emit the newly created withdrawal ID, as you can see below:

Response:

Resolve redemption request

In order to see if a redemption request can be satisfied, use the function call.

Request:

Response:

You receive a redeem ID of 10. 10 is the specific withdrawal event ID that is produced when the Liquid Collective Protocol has enough ETH to satisfy (either partial or full) the redemption. This means that the redeemRequest has been satisfied and the corresponding withdrawal event ID was returned.

This withdrawal event may fully satisfy or partially satisfy the redeem request ID. To ensure redemption requests are fully satisfied prior to claiming, use the /eth/v0/redeems/{idx} endpoint.

A response of…

-1 means that the request is not satisfied yet
-2 means that the request is out of bounds

An alternative method to getting the Withdrawal event ID is using the /eth/v0/redeems/{id} endpoint.

Request:

Response:

The response below indicates that this redemption can be fully satisfied, meaning there is enough supply in the withdrawal stack to fulfill this redemption. This is noted via the "status_satisfaction": "FULLY_SATISFIED" and also the claimable_amount_lseth is equal to the total_amount_lseth.

For other potential states, check out the at the bottom of the doc.

Claim redemption requests

With both a request redeem ID and withdrawal event ID you can submit a claim for the redemption calling the function.

Before claiming, ensure you have correct Withdrawal event ID. Withdrawal events IDs will change based on redemptions happening on the protocol.

Request:

After making a claim there will be two events triggered, which will be inspected next in this guide.

ClaimedRedeemRequest event

On successfully claiming a redeemRequest, a ClaimedRedeemRequest event is emitted. This event indicates the amount of LsETH claimed, the amount of ETH sent to the recipient, and the remaining LsETH amount that has been satisfied but not yet claimed.

A remaining LsETH amount of 0 means the request has been fully claimed. If the amount is greater than 0, the request has been partially claimed and another claim will be required to fully claim the request.

Request:

Response:

SatisfiedRedeemRequest event

On successfully claiming a redemption request one or more SatisfiedRedeemRequest events are emitted.

Those events provide details about the withdrawal events that have satisfied a redemption request.

Request:

Response:

eth/v0/redeems

An alternative approach is to use the Alluvial API to call the /redeems endpoint, as it will return the status of both satisfaction and claim status.

Request:

Non-finalized blocks are returned in the Alluvial API.

Response:

Below the endpoint returns that this request redeem has been fully satisfied and claimed.

You are now able to fully implement the redemption process for the Liquid Collective protocol!

Redemption Information

The Alluvial API exposes information about both the.

Redemption height

Platforms who want visibility into the current supply (amount of withdrawals) and demand (amount of redeems) can use the /redeems_info endpoint.

Request:

Response:

Below you can see that the redeem queue is greater than the withdrawal stack. This indicates that more supply is needed to fulfill the redeem requests. Additional supply can enter via more deposits and/or exiting a validator.

amounts returned are denominated in LsETH

In addition to exposing the Withdrawal stack and Redeem queue, Alluvial exposes an estimated time when redeems will be fulfilled.

Request:

Response:

The current projections timestamp logic is:

If the timestamp is in the past, it means that there is enough supply to fulfill demand and Alluvial returns the timestamp associated with the latest redeem request.
If the timestamp is in the future, it means there isn't enough supply to fulfill demand and time is needed to add supply into the Withdrawal stack.

This is an estimated time and actual times may vary depending on frequency of deposits and redemptions on the Liquid Collective protocol.

Appendix

Full Code

Full code for making deposit transaction

Code is meant for testing purposes and should not be used directly for production workloads.

/redeems response payloads

The redemption process is very dynamic. You can see a matrix of all the redeem statuses . Below will show the difference between response payloads when requesting from either:

eth/v0/redeems/18
eth/v0/redeems?owner=