smart contracts: Update "fundEscrow" function

[JoelVR17]

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

Description:

Currently, the “fundEscrow” function of the contract allows funding the contract in two executions, adding half of the value defined in the “amount” property of the escrow with each execution. However, this behavior limits the flexibility in funding the escrows, which is not ideal for certain cases where larger deposits are required on specific dates prior to pre-set milestones.

Requirements:

We need to modify the fundEscrow function of the contract (in the file named contract.rs) to allow the possibility of adding any amount at any time, respecting the following conditions:

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. The value of the deposit must not exceed the value of the escrow property “amount”.
3. The function must allow flexible deposits until the accumulated value equals the amount of the escrow property.
4. The function should allow the signer to deposit any amount he/she wishes to the contract.
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.

This change is necessary to provide greater flexibility in the management of escrows, allowing partial or full deposits to be made as needed, without the current limitation of two equal anchorages.

Validations:

1. The amount to be melted must not exceed the amount defined by the “amount” property of the escrow.
2. The engagement id must match the one already defined for the escrow. Otherwise, this means that the escrow has not been initialized.
3. It must be validated that the escrow has not been fully funded. This can be done by comparing the balance of the contract with that defined by the “amount” property of the escrow. If this is less than the contract balance, it means that the escrow has not been fully funded.
4. The “dispute_flag” property must be set to false. Otherwise, it means that the escrow has been opened for dispute resolution.

Function parameters:

• engagement_id (type: String) → Escrow Identifier.
• signer (type: Address) → Wallet in charge of signing the transaction.
• usdc_contract (type: Address) → usdc contract address, address of the token with which usdc amounts are managed.
• amount (type: u128) → Amount the signer wishes to deposit to the contract.

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

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. The escrow must be initialized (intialize_escrow).
2. The escrow must be funded correctly (fund_escrow).
3. Verify that the escrow has not been fully funded before.
4. Verify that the amount of USDC with which you are attempting to fund the escrow does not exceed the “amount” property of the escrow.
5. Verify that the client has decreased the balance and the contract has increased its balance by the amount of USDC with which the escrow was funded.
6. 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 your_test_name() {
    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. ⚠️

[Jemiiah]

Hello please i would love to work on this issue

[Bosun-Josh121]

I am applying to this issue via OnlyDust platform.

My background and how it can be leveraged:

software engineering background, backend & smart contract dev with contribution to similar tasks(https://app.onlydust.com/u/Josh-121) looking to make first contribution on this project

How I plan on tackling this issue I have a good understanding of the requirements & would make necessary updates, I would work on feedback & recommendation ensuring contact. Can deliver within a day upon assignment

[danielcdz]

GM! I have experience working with SM in Cairo and Solidity, and I think I can handle this quite well, can I help you guys solve this issue?

[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’d like to resolve this.

[mexes20]

May I pick this up? I have three years experience in Software development and have contributed to some projects on OD here.

ETA: 10 hours.

[KoxyG]

I am applying through OnlyDust to contribute to this project. I have hands-on experience with Soroban smart contracts.

I can modify the fundEscrow function to:

• Support flexible deposits until the total matches the escrow’s amount property.
• Ensure deposits do not exceed the amount limit.
• Dynamically retrieve the contract address using the Soroban SDK to transfer funds.

This update will allow more flexible escrow management, supporting partial and full deposits without restrictions. I will also ensure the changes align with the updated escrow properties and write tests to validate the new functionality.

Looking forward to contributing to this project.

[martinvibes]

Can I take care of this issue? i'm a frontend dev and a blockchain dev please kindly assign :)

[zkCaleb-dev]

This issue is for you @danielcdz ! 🚀 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. 🔥