Support retrieve last received object in Move tests

[lxfind]

Add a new test-only Move library function that allows us to retrieve the most recent object received through transfer by the current signer. This will allow us to inspect the received object without exiting Move, and unblock many ways to test move code.
Added a test.

[sblackshear]

So excited for the devx improvement this will bring!

Have some ideas about setting up the API's to allow testing more scenarios, but love the direction.

[sblackshear]

I think test-only functions should have 0 gas cost to perturb the gas results as little as possible.

[lxfind]

Removed the TODO. The gas amount doesn't really matter here.

[sblackshear]

• I think this would be more general if it took an address instead of TxContext. If we are trying to test a function that transfers to someone other than the tx sender, I believe we will need this.
• Similarly, I think we will need to test functions/tx workflows that transfer >1 object. For this, perhaps we should also expose something like get_transfer<T: key>(n: u64): T that gives you the nth object transferred by this transaction.

To suggest one concrete combination of API's

#[test_only]
module FastX::TestTransfer {
/// Return the last object transferred by the current transaction
/// Aborts if the transaction has not transferred any objects or the last transfer does not have type `T`
public fun get_last_transfer<T: key>(): T

/// Return the last object transferred by the current transaction
/// Aborts if index is out of bounds or the `index`th transfer does not have type T
public fun get_transfer<T: key>(index: u64): T

/// Get the last object of type `T` transferred to address `a`. 
/// Aborts if there have been no transfers to `a`, or if the last transfer to `a` did not have type `T`
public fun get_last_transfer_to<T: key>(a: Address): T

/// Return the number of transfers performed by the current transaction
public fun num_transfers(): u64
}

[lxfind]

Yeah makes sense. I will add more APIs in a separate PR.
(this PR is to support retrieve last received object)

[sblackshear]

On board re adding the others later. But I think generalizing to

public fun get_last_transfer_to<T: key>(a: Address): T

(or similar) here probably makes sense? get_last_received_object<T: key>(ctx: &TxContext) seems a bit too narrow--I'm guessing most transfers will be to addresses other than the tx sender.

[lxfind]

hmm not sure. My assumption for how people might write tests using this is that they want to consume / use the objects received in some way, and to do that they often need the TxContext. So a typical test will always start by creating a few TxContext, each representing an account, and from there the TxContext represents the address. Basically even though we don't have authentication in tests, we could still try to mimic it as much as possible through TxContext.

[sblackshear]

On board re adding the others later. But I think generalizing to

public fun get_last_transfer_to<T: key>(a: Address): T

(or similar) here probably makes sense? get_last_received_object<T: key>(ctx: &TxContext) seems a bit too narrow--I'm guessing most transfers will be to addresses other than the tx sender.

[huitseeker]

🚀