Add Native SAC mint capabilities in tests

[teddav]

What problem does your feature solve?

Working with native tokens (XLM) in unit tests is unnecessarily complicated, and CAP-73 now lets contracts create G-accounts, but testing that flow requires funding those accounts with native tokens, something the SDK doesn't directly support.

There are two specific gaps.

1. No straightforward way to obtain the native SAC.

I work around it like this:

fn register_native_sac(env: &Env) -> Address {
    let asset = Bytes::from_slice(env, &[0, 0, 0, 0]);
    env.deployer().with_stellar_asset(asset).deploy()
}

@aolieman uses a similar approach.

But even once you have the SAC, there's no way to mint into it.

2. No way to fund G-accounts.

For C-addresses, Address::generate() from testutils works fine. For G-accounts, the only path I've found is to manually construct a ledger entry and inject it via the host:

fn generate_funded_g_account(env: &Env, stroops: i64) -> Address {
    let pk: [u8; 32] = BytesN::<32>::random(env).to_array();
    let account_id = xdr::AccountId(xdr::PublicKey::PublicKeyTypeEd25519(xdr::Uint256(pk)));
    let key = Rc::new(xdr::LedgerKey::Account(xdr::LedgerKeyAccount {
        account_id: account_id.clone(),
    }));
    let entry = Rc::new(xdr::LedgerEntry {
        data: xdr::LedgerEntryData::Account(xdr::AccountEntry {
            account_id: account_id.clone(),
            balance: stroops,
            flags: 0,
            home_domain: Default::default(),
            inflation_dest: None,
            num_sub_entries: 0,
            seq_num: xdr::SequenceNumber(0),
            thresholds: xdr::Thresholds([1; 4]),
            signers: xdr::VecM::default(),
            ext: xdr::AccountEntryExt::V0,
        }),
        last_modified_ledger_seq: 0,
        ext: xdr::LedgerEntryExt::V0,
    });
    env.host().add_ledger_entry(&key, &entry, None).unwrap();
    Address::try_from_val(env, &xdr::ScAddress::Account(account_id)).unwrap()
}

This depends on internal host APIs and a lot of XDR boilerplate. Again, @aolieman has similar workaround code.
Multiple users converging on the same hacks suggests this belongs in testutils.

What would you like to see?

Two additions to testutils:

1. A helper to obtain the native SAC, e.g. env.native_asset_contract() or an equivalent on Env/StellarAssetContract.
2. A way to mint native tokens in tests, either by exposing admin capabilities on the native SAC, or via a dedicated env.fund_account(address, stroops) helper that works for both G- and C-addresses.

Together these would make CAP-73 end-to-end testable: contracts that create and fund G-accounts could be exercised in unit tests without resorting to host-level ledger entry injection.

As a related note (probably worth a separate issue): distinguishing C-addresses from G-addresses given an Address is also harder than it should be (both in test and also in contract code). A built-in way to check the address type would pair well with the helpers above.

[aolieman]

This question comes up regularly. Not that often, since usually there is no real need to test with the native SAC per se. Still, there is an unfulfilled need here—in the cases that do benefit from using the actual native SAC and balance, instead of a generic placeholder SAC.

The desire to test with the native SAC goes back to at least 2023: https://discord.com/channels/897514728459468821/1145462925109231726

I added to a thread that was started by @esteblock, in which I think we had different motivations but still needed the same helper function that is intentionally not present in the SDK.

[leighmcculloch]

Thanks @teddav @aolieman. Some thoughts on what these helpers could look like.

I'd like to optimise for allowing folks to work with native in tests, while keeping the behaviour of C and G addresses seamless from the test author's point of view. One method should fund either, regardless of address kind, and tests should not have to branch on it. Alongside that, add as little as possible that is bespoke about the native asset.

With that in mind, here is an approach we could take:

impl Env {
    pub fn register_stellar_asset_contract_v2(&self, admin: Address) -> StellarAssetContract; // existing
    pub fn register_stellar_asset_contract_native(&self) -> NativeAssetContract;              // new
}

impl StellarAssetContract { // existing
    pub fn address(&self) -> Address;                       // existing
    pub fn issuer(&self) -> StellarAssetIssuer;             // existing
    pub fn set_balance(&self, addr: &Address, amount: i128); // new
}

impl NativeAssetContract { // new
    pub fn address(&self) -> Address; // new
    pub fn set_balance(&self, addr: &Address, amount: i128); // new
}

set_balance would work for both G- and C-addresses, and it would navigate writing to the approprirate ledger entry directly. There would be no operation being executed to make this happen, it's directly ledger entry modification.

• credit + G: TrustLine entry
• credit + C: ContractData::Balance on the SAC
• native + G: AccountEntry.balance
• native + C: ContractData::Balance on the native SAC

register_stellar_asset_contract_native could be idempotent. The contract id is deterministic from Asset::Native, so repeat calls return the same NativeAssetContract.

The user story is roughly:

let env = Env::default();
let native = env.register_stellar_asset_contract_native();

let funder = Address::generate(&env);
native.set_balance(&funder, 100_000_000); // 10 XLM

let recipient = Address::from_str(&env, "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF");
// CAP-73: transfer auto-creates the recipient G-account if it does not exist.
TokenClient::new(&env, &native.address()).transfer(&funder, &recipient, &50_000_000);

The consistent behaviour for G and C addresses is important for hiding as much as possible the need to use a G address. I'd like to avoid adding a new utility for generating a G address right now. In most cases we've seen, contracts and tests do not need to distinguish between C and G addresses, and in the past when utilities existed for G address special, they drew attention to the distinction and led developers to writing code that branches on address kind unnecessarily, which produced odd behaviour and bugs that would not exist if the code treated Address as opaque. For the rare case someone really needs a G address, they can create one using Address::from_str(env, "G..."), or use MuxedAddress::generate(env).address(). I realise it is a bit obscure as a way to get a G-Address for tests. We can revisit G address generation utilities, but I would rather start without them. And the other changes proposed conveniently work consistently for G or C because CAP-73 is really about making a transfer to a not-yet-existing G work the same as it does for a C today.

On the address kind check side note: take a look at AddressPayload (and Address::to_payload, behind the hazmat-address feature) if you really need it. It's a hazmat API because as mentioned above, we've seen some odd use when folks start asserting on the address type.

Happy to continue to talk through this. Keen to hear what you think.

[teddav]

Thanks @leighmcculloch !
The new functions look good!
Regarding the C/G addresses, AddressPayload is not practical to use at all.
Exposing a helper for that seems like the better solution. You shouldn't make it hard "because developers could end up doing odd things with it". This way, you're just forcing the developers to write "complicated" work-arounds, and expose them to even more bugs. If a dev wants to differentiate between C and G addresses, we should be able to.
My use case is that I want to send tokens to an address:

• if it's a C-address, I can just send anything
• if it's a G-address, I can send XLM to it (cap-73), but other tokens only if it has a trustline. Otherwise I need to call trust() before.

[tupui]

if it's a G-address, I can send XLM to it (cap-73), but other tokens only if it has a trustline. Otherwise I need to call trust() before.

On that one, we could solve it if the call was a no-op on C-addresses. Unless there is a trust define on the contract maybe. This is something we might be proposing working on this RFP https://stellar.gitbook.io/scf-handbook/scf-awards/build-award/rfp-track#trustline-onboarder You might want to have a trustline setup on C-tokens too. So having a canonical way to do this would be good.

[leighmcculloch]

You should be able to call .trust() with a C address and it should be a no-op.

See:

/// Creates this contract asset's unlimited trustline for the provided address.
///
/// This is no-op if the input address is a C-address, or if provided G-address
/// already has the respective trustline.
///
/// If the trustline is actually created, this will require 
/// authorization from `address` (i.e. `address.require_auth` will be called).
///
/// Panics only during trustline creation if the asset issuer does not exist, or
/// when a new trustline can not be created.
fn trust(env: Env, address: Address);

Ref: https://github.com/stellar/stellar-protocol/blob/45ad2a3/core/cap-0073.md?plain=1#L52-L62