smart contracts: Update “claim_escrow_earnings” function

[JoelVR17]

You must apply through OnlyDust. If not, you'll be ignored

Issue - Update “claim_escrow_earnings” function.

Description:

You need to update the “claim_escrow_earnings” function of the contract. This function ensures that the service provider gets the rewards for completing the escrow.

Requirements:

1. Some of the properties used in this function have been renamed, are no longer used or are used in a different way within the escrow. Therefore, it is necessary to pay attention to the changes that were made in the escrow properties and adapt them to the function.
2. A 0.3% commission should be deducted from the amount to be claimed and transferred to the TW address.
3. The 0.3% commission for Trustless Work should be transferred to the following address: GBPUACN7QETR4TCYTKINBDHTYTFXD3BQQQV7VSMZC5CX74E4MTUL2AMUB
4. From the amount to be claimed you should take the platform fee which is defined in the contract properties (specifically in the property called “platform_fee”). This commission should be transferred to the platform address, which can also be obtained from the contract properties (platform_address). This commission is also taken from the amount that the service provider is about to claim.
5. You must find a way to interact with the contract to get the contract address and with this address transfer the contract USDC to the service provider address. Currently the contract address is received via the parameters of the function (contract_address), but this should not be necessary as the soroban_sdk library provides a way to interact with the contract and get the contract address.
6. The amount in cryptocurrency that the service provider will claim should be taken from the escrow amount, not from the contract balance.

The function must receive the following parameters:

1. engagement_id: String
2. service_provider: Address
3. usdc_contract: Address

Note: Feel free to add more parameters to the function if necessary.

Validations:

1. Verify that the escrow has been defined by means of its engagement_id. Otherwise, this means that the escrow has not been initialized.
2. Only the service provider can perform this function.
3. This function can only be executed if the escrow has at least 1 milestone defined. Since there is a possibility that the escrow was initially initialized without any milestone.
4. You can only claim the earnings if all the milestones have been defined as completed by the client. This can be done by verifying that all milestones have the “flag” property set to true.
5. Verify that the contract balance is equal to or greater than that defined by the “amount” property of the escrow.
6. The “dispute_flag” property must be set to false. Otherwise, it means that the escrow has been opened for dispute resolution.

Errors:

We currently have a number of custom errors which we throw when executing some of the contract functions. An example of the above would be the following:

if escrow.balance != escrow.amount {
      return Err(ContractError::EscrowBalanceNotSufficienteToSendEarnings);
}

You only need to worry about throwing the error message, you don't need to handle custom errors. So if you need to return an error within the flow due to one of the validations, you can do it as follows:

if escrow.balance != escrow.amount {
      return Err("Your error message");
}

You must make sure that the message you are sending as an error is very clear and makes sense as to why the error is being sent.

Tests:

In the test.rs file you must develop the following test to check that the contract flow works correctly together with the function you have just built:

1. Initialize an escrow (initialize_escrow) with all the “flag” properties of the milestones set to “true”.
2. Fund an escrow but not using the “fund_escrow” function of the contract, but doing it directly with the token we created for this type of testing. With this token you will be able to transfer funds to the escrow contract so that they can be claimed by the service provider (the token code can be found in the file called token.rs).
3. Claim earnings (claim_escrow_earnings).
4. Verify that the escrow has at least 1 milestone. Otherwise the test must fail.
5. Verify that Trustless Work management has received the 0.3% commission based on the amount in USDC that the service provider is about to claim.
6. Verify that the platform address (platform_address) has received the commission defined in the “platform_fee” property according to the amount in USDC that the service provider is about to claim.
7. Verify that the service provider has received all the money that the contract had in balance (taking into account the usdc that was subtracted for commissions).
8. Verify by means of this test that the validations mentioned above are working correctly.

You can rely on the previously created tests to complete your test. The important thing is that you succeed in testing your code and that it works well in conjunction with the entire contract flow which is explained in the list above. Also, please note that you should not create a test for each of the items in the above list. This list indicates with each of its items the flow that must contain the only test that you must create to verify that the code you made works. You can also create more than 1 test if necessary, but if you do, you must justify why.

⚠️ Important: Please define a clear name for the test so that the purpose of the test is clearly understood.

This is an example of how to initialize our test token in our test.rs file:

use crate::token::{ Token, TokenClient };
use soroban_sdk::{Address, Env};

fn create_token<'a>(e: &Env, admin: &Address) -> TokenClient<'a> {
    let token = TokenClient::new(e, &e.register_contract(None, Token {}));
    token.initialize(admin, &7, &"name".into_val(e), &"symbol".into_val(e));
    token
}

#[test]
fn test_create_fund_complete_escrows() {
  let env = Env::default();
  env.mock_all_auths();

  let admin = Address::generate(&env);
  let signer_address = Address::generate(&env);
  let token = create_token(&env, &admin);

  assert_eq!(token.balance(&signer_address), 1_000_000_000);
}

To run the test you have just created you can use the command cargo test.

Recommendation:

Stellar people have in their discord a channel called “stella-help”, in that channel you can ask your technical questions about Stellar and its libraries (including the “soroban_sdk” library we use in the contract). This bot can help you a lot to solve your issues. Just remember that before submitting your query you must add the word “stella” at the beginning of the query. Otherwise the bot will not answer you. The Stellar discord where you can find this channel is the following: Stellar Discord

⚠️ Please follow the guidelines for requesting an issue, launching commits and describing PR's. Otherwise they will be ignored. ⚠️

[jimenezz22]

Hello sir! Here Luis from Dojo Coding! I would like to work on this issue, I have experience with the stellar ecosystem with a previous contribution to the Basic Payment App Project, and have contributed to similar projects involving testing and smart contracts. I understand the requirements, including handling escrow logic, fees, and validations.

Could you assign this to me? Thank you!

[Kom02]

Hi, My name is Kevin Obando, a full stack junior developer with 2 years of experience from Costa Rica. I am starting in this community and I want to help in this project.

[CollinsC1O]

I would love to take on this

[MrRoudyk]

Can I take care of this issue?

[NueloSE]

I'd be happy to do this.

i will follow through the project description guide and implement claim escrow functionality. ETA <=2days

[JoE11-y]

May I be assigned to this?

[KoxyG]

Hi, I am koxy.

I am applying through OnlyDust to contribute to this project. I am an active contributor to the Stellar ecosystem and run a video series called Let's Get Soroban to teach developers about Soroban smart contracts. You can view my work here: Let's Get Soroban - YouTube.

I can update the claim_escrow_earnings function to:

• Deduct the 0.3% Trustless Work commission and platform fees and transfer them correctly.
• Use the Soroban SDK to retrieve the contract address dynamically.
• Validate milestones, dispute status, and escrow balance to ensure proper payouts.

I will also write tests to confirm the flow works correctly, including commission deductions and payouts to the service provider.

Looking forward to contributing to this project. This version is direct and easy to read while covering all the essential points.

[armandocodecr]

This issue is for you @jimenezz22 ! 🚀 Remember to follow all the guidelines, both the ones inside the repository and the guideline to perform the PR.

Many thanks to all the other dev's who sent in their application. 🔥