Add mint event with mux support and other memo types to specs (#1555)

### What
Add a new Mint event with muxed address support. Add events to specs for
other memo types that can occur with payments from classic.

  ### Why
The mint event should be defined so that contract developers can choose
to emit a mint event to a destination with a muxed id.

The specs should contain all of the event structures that an ingester
could potentially see, including when other memo types are in use.

### Tests

It wasn't possible to add comparison tests for the mint muxed event, or
the mint memo string and bytes to_muxed_id types, to confirm the events
are identical. This is because the soroban-env doesn't allow us to
trigger those events because they are only generated by the classic
transaction processing.

For this reason @dmkozh @sisuresh please take great care to review the
events being added. I've written them based on CAP-67, but we've had
bugs in the past arise out of out-dated CAPs, so your help in validating
they match core's implementation is much appreciated.

Close #1554

Author: leighmcculloch

soroban-token-sdk/src/events.rs

@@ -11,7 +11,7 @@ pub struct Approve {
 }
 
 #[contractevent(topics = ["transfer"], data_format = "single-value")]
-pub struct TransferLegacy {
+pub struct TransferWithAmountOnly {
     #[topic]
     pub from: Address,
     #[topic]
@@ -37,9 +37,17 @@ pub struct Burn {
 }
 
 #[contractevent(topics = ["mint"], data_format = "single-value")]
+pub struct MintWithAmountOnly {
+    #[topic]
+    pub to: Address,
+    pub amount: i128,
+}
+
+#[contractevent(topics = ["mint"], data_format = "map")]
 pub struct Mint {
     #[topic]
     pub to: Address,
+    pub to_muxed_id: Option<u64>,
     pub amount: i128,
 }
 

soroban-token-sdk/src/tests/events.rs

@@ -3,7 +3,9 @@ extern crate std;
 use core::i64;
 use std::rc::Rc;
 
-use crate::events::{Approve, Burn, Clawback, Mint, Transfer, TransferLegacy};
+use crate::events::{
+    Approve, Burn, Clawback, Mint, MintWithAmountOnly, Transfer, TransferWithAmountOnly,
+};
 use soroban_sdk::{
     contract, symbol_short,
     testutils::{Address as _, Events as _, MuxedAddress as _},
@@ -66,15 +68,15 @@ fn test_approve() {
 }
 
 #[test]
-fn test_transfer_legacy() {
+fn test_transfer_with_amount_only() {
     let env = Env::default();
     env.mock_all_auths();
 
     let from = Address::generate(&env);
     let to = Address::generate(&env);
     let amount = 123;
 
-    let event = TransferLegacy {
+    let event = TransferWithAmountOnly {
         from: from.clone(),
         to: to.clone(),
         amount,
@@ -154,9 +156,9 @@ fn test_transfer_without_id() {
 
     // No comparison is made with the Stellar Asset Contract for publishing Transfer with a
     // MuxedAddress that does not contain an ID, because the Stellar Asset Contract for legacy
-    // reasons, to minimise the changes to its behavior over time, still publishes TransferLegacy
-    // in this case. See [`test_transfer_with_id`] for a test that exercises Transfer in the case
-    // that the Stellar Asset contract does publish that event.
+    // reasons, to minimise the changes to its behavior over time, still publishes
+    // TransferWithAmountOnly in this case. See [`test_transfer_with_id`] for a test that exercises
+    // Transfer in the case that the Stellar Asset contract does publish that event.
 }
 
 #[test]
@@ -296,14 +298,14 @@ fn test_burn() {
 }
 
 #[test]
-fn test_mint() {
+fn test_mint_with_amount_only() {
     let env = Env::default();
     env.mock_all_auths();
 
     let to = Address::generate(&env);
     let amount = 123;
 
-    let event = Mint {
+    let event = MintWithAmountOnly {
         to: to.clone(),
         amount,
     };
@@ -342,6 +344,78 @@ fn test_mint() {
     );
 }
 
+#[test]
+fn test_mint_without_id() {
+    let env = Env::default();
+    env.mock_all_auths();
+
+    let to: MuxedAddress = MuxedAddress::generate(&env).address().into();
+    let amount = 123;
+
+    let event = Mint {
+        to: to.address(),
+        to_muxed_id: to.id(),
+        amount,
+    };
+
+    // Verify the event publishes the expected topics and data.
+    let topics = (symbol_short!("mint"), to.address());
+    let data = Map::<Symbol, Val>::from_array(
+        &env,
+        [
+            (Symbol::new(&env, "to_muxed_id"), Val::VOID.to_val()),
+            (Symbol::new(&env, "amount"), amount.into_val(&env)),
+        ],
+    );
+
+    let id = env.register(Contract, ());
+    env.as_contract(&id, || event.publish(&env));
+    let token_events = env.events().all();
+    assert_eq!(
+        token_events,
+        vec![
+            &env,
+            (id.clone(), topics.into_val(&env), data.into_val(&env))
+        ]
+    );
+}
+
+#[test]
+fn test_mint_with_id() {
+    let env = Env::default();
+    env.mock_all_auths();
+
+    let to = MuxedAddress::generate(&env);
+    let amount = 123;
+
+    let event = Mint {
+        to: to.address(),
+        to_muxed_id: to.id(),
+        amount,
+    };
+
+    // Verify the event publishes the expected topics and data.
+    let topics = (symbol_short!("mint"), to.address());
+    let data = Map::<Symbol, Val>::from_array(
+        &env,
+        [
+            (Symbol::new(&env, "to_muxed_id"), to.id().into_val(&env)),
+            (Symbol::new(&env, "amount"), amount.into_val(&env)),
+        ],
+    );
+
+    let id = env.register(Contract, ());
+    env.as_contract(&id, || event.publish(&env));
+    let token_events = env.events().all();
+    assert_eq!(
+        token_events,
+        vec![
+            &env,
+            (id.clone(), topics.into_val(&env), data.into_val(&env))
+        ]
+    );
+}
+
 #[test]
 fn test_clawback() {
     let env = Env::default();

…_snapshots/tests/events/test_mint.1.json …events/test_mint_with_amount_only.1.jsonsoroban-token-sdk/test_snapshots/tests/events/test_mint.1.json renamed to soroban-token-sdk/test_snapshots/tests/events/test_mint_with_amount_only.1.json soroban-token-sdk/test_snapshots/tests/events/test_mint.1.json renamed to soroban-token-sdk/test_snapshots/tests/events/test_mint_with_amount_only.1.json

@@ -0,0 +1,118 @@
+{
+  "generators": {
+    "address": 2,
+    "nonce": 0,
+    "mux_id": 1
+  },
+  "auth": [
+    [],
+    []
+  ],
+  "ledger": {
+    "protocol_version": 23,
+    "sequence_number": 0,
+    "timestamp": 0,
+    "network_id": "0000000000000000000000000000000000000000000000000000000000000000",
+    "base_reserve": 0,
+    "min_persistent_entry_ttl": 4096,
+    "min_temp_entry_ttl": 16,
+    "max_entry_ttl": 6312000,
+    "ledger_entries": [
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+            "key": "ledger_key_contract_instance",
+            "durability": "persistent"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+                "key": "ledger_key_contract_instance",
+                "durability": "persistent",
+                "val": {
+                  "contract_instance": {
+                    "executable": {
+                      "wasm": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+                    },
+                    "storage": null
+                  }
+                }
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ],
+      [
+        {
+          "contract_code": {
+            "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_code": {
+                "ext": "v0",
+                "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                "code": ""
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ]
+    ]
+  },
+  "events": [
+    {
+      "event": {
+        "ext": "v0",
+        "contract_id": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+        "type_": "contract",
+        "body": {
+          "v0": {
+            "topics": [
+              {
+                "symbol": "mint"
+              },
+              {
+                "address": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAC6PV"
+              }
+            ],
+            "data": {
+              "map": [
+                {
+                  "key": {
+                    "symbol": "amount"
+                  },
+                  "val": {
+                    "i128": "123"
+                  }
+                },
+                {
+                  "key": {
+                    "symbol": "to_muxed_id"
+                  },
+                  "val": {
+                    "u64": "1"
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      "failed_call": false
+    }
+  ]
+}