Include the token interface in the stellar asset interface (#1427)

### What
Include the token interface in the stellar asset interface, and
therefore also in the client.

### Why
The separation of the token functions from the stellar asset interface
and client was originally done to ensure that developers didn't use the
stellar asset client in situations where they really should be using the
token client, to interface with tokens of any kind.

However, most of the time when people discover the stellar asset client
is missing those functions, it creates confusion. It always requires an
explanation. I think this is largely because in all other situations
clients contain all the functions of a contract.

After discussing this with @tomerweller, who was the most recent person
to run into this, I think while we had good intentions, it has landed
with different impact than we thought it'd have.

### How
The approach taken to the changes was to manually copy-paste the
functions across the two interfaces. A macro could be used here but
because any macro used here would need to interact well with the
attribute macros in use on the traits, the complexity isn't worth it. It
is unlikely the two will get out of sync because tests have been added
to ensure the token spec is a subset of the stellar asset spec.

As part of the change I needed to fix a minor bug where the contractspec
macro still wrote out a static variable even when exporting was
disabled. Normally we don't allow more than one exported function with
the same name per module. We have exporting turned off in this code, but
the code was still generating the variable to export resulting in a
collision since both interfaces contain functions with the same names.

Author: leighmcculloch

soroban-sdk-macros/src/derive_spec_fn.rs

@@ -157,8 +157,15 @@ pub fn derive_fn_spec(
         return Err(quote! { #(#compile_errors)* });
     }
 
-    let export_attr = if export {
-        Some(quote! { #[cfg_attr(target_family = "wasm", link_section = "contractspecv0")] })
+    let exported = if export {
+        Some(quote! {
+            #[doc(hidden)]
+            #[allow(non_snake_case)]
+            #[allow(non_upper_case_globals)]
+            #(#attrs)*
+            #[cfg_attr(target_family = "wasm", link_section = "contractspecv0")]
+            pub static #spec_ident: [u8; #spec_xdr_len] = #ty::#spec_fn_ident();
+        })
     } else {
         None
     };
@@ -171,12 +178,7 @@ pub fn derive_fn_spec(
 
     // Generated code.
     Ok(quote! {
-        #[doc(hidden)]
-        #[allow(non_snake_case)]
-        #[allow(non_upper_case_globals)]
-        #(#attrs)*
-        #export_attr
-        pub static #spec_ident: [u8; #spec_xdr_len] = #ty::#spec_fn_ident();
+        #exported
 
         impl #ty {
             #[allow(non_snake_case)]

soroban-sdk/src/tests/token_spec.rs

@@ -1,16 +1,29 @@
 use crate as soroban_sdk;
+use std::collections::HashSet;
 
 use soroban_sdk::{
-    token::{StellarAssetSpec, SPEC_XDR_INPUT, SPEC_XDR_LEN},
+    token::{
+        StellarAssetSpec, TokenSpec, STELLAR_ASSET_SPEC_XDR_INPUT, STELLAR_ASSET_SPEC_XDR_LEN,
+        TOKEN_SPEC_XDR_INPUT, TOKEN_SPEC_XDR_LEN,
+    },
     xdr::{Error, Limited, Limits, ReadXdr, ScSpecEntry},
 };
 
 extern crate std;
+#[test]
+fn test_stellar_asset_spec_xdr_len() {
+    let len = STELLAR_ASSET_SPEC_XDR_INPUT
+        .iter()
+        .fold(0usize, |sum, x| sum + x.len());
+    assert_eq!(STELLAR_ASSET_SPEC_XDR_LEN, len);
+}
 
 #[test]
-fn test_spec_xdr_len() {
-    let len = SPEC_XDR_INPUT.iter().fold(0usize, |sum, x| sum + x.len());
-    assert_eq!(SPEC_XDR_LEN, len);
+fn test_token_spec_xdr_len() {
+    let len = TOKEN_SPEC_XDR_INPUT
+        .iter()
+        .fold(0usize, |sum, x| sum + x.len());
+    assert_eq!(TOKEN_SPEC_XDR_LEN, len);
 }
 
 #[test]
@@ -22,3 +35,37 @@ fn test_spec_xdr() -> Result<(), Error> {
     }
     Ok(())
 }
+
+#[test]
+fn test_token_spec_xdr() -> Result<(), Error> {
+    let xdr = TokenSpec::spec_xdr();
+    let cursor = std::io::Cursor::new(xdr);
+    for spec_entry in ScSpecEntry::read_xdr_iter(&mut Limited::new(cursor, Limits::none())) {
+        spec_entry?;
+    }
+    Ok(())
+}
+
+#[test]
+fn test_stellar_asset_spec_includes_token_spec() -> Result<(), Error> {
+    // Read all TokenSpec entries
+    let token_xdr = TokenSpec::spec_xdr();
+    let token_cursor = std::io::Cursor::new(token_xdr);
+    let token_entries: HashSet<ScSpecEntry> =
+        ScSpecEntry::read_xdr_iter(&mut Limited::new(token_cursor, Limits::none()))
+            .collect::<Result<HashSet<_>, _>>()?;
+
+    // Read all StellarAssetSpec entries
+    let stellar_asset_xdr = StellarAssetSpec::spec_xdr();
+    let stellar_asset_cursor = std::io::Cursor::new(stellar_asset_xdr);
+    let stellar_asset_entries: HashSet<ScSpecEntry> =
+        ScSpecEntry::read_xdr_iter(&mut Limited::new(stellar_asset_cursor, Limits::none()))
+            .collect::<Result<HashSet<_>, _>>()?;
+
+    // Check that the token entries are a subset of stellar entries
+    assert!(
+        token_entries.is_subset(&stellar_asset_entries),
+        "StellarAssetSpec is missing entries from TokenSpec"
+    );
+    Ok(())
+}

soroban-sdk/src/token.rs

@@ -80,7 +80,7 @@ pub use TokenClient as Client;
 /// There are no functions in the token interface for minting tokens. Minting is
 /// an administrative function that can differ significantly from one token to
 /// the next.
-#[contractspecfn(name = "StellarAssetSpec", export = false)]
+#[contractspecfn(name = "TokenSpec", export = false)]
 #[contractclient(crate_path = "crate", name = "TokenClient")]
 pub trait TokenInterface {
     /// Returns the allowance for `spender` to transfer from `from`.
@@ -230,11 +230,205 @@ pub trait TokenInterface {
     fn symbol(env: Env) -> String;
 }
 
+/// Spec contains the contract spec of Token contracts.
+#[doc(hidden)]
+pub struct TokenSpec;
+
+pub(crate) const TOKEN_SPEC_XDR_INPUT: &[&[u8]] = &[
+    &TokenSpec::spec_xdr_allowance(),
+    &TokenSpec::spec_xdr_approve(),
+    &TokenSpec::spec_xdr_balance(),
+    &TokenSpec::spec_xdr_burn(),
+    &TokenSpec::spec_xdr_burn_from(),
+    &TokenSpec::spec_xdr_decimals(),
+    &TokenSpec::spec_xdr_name(),
+    &TokenSpec::spec_xdr_symbol(),
+    &TokenSpec::spec_xdr_transfer(),
+    &TokenSpec::spec_xdr_transfer_from(),
+];
+
+pub(crate) const TOKEN_SPEC_XDR_LEN: usize = 4716;
+
+impl TokenSpec {
+    /// Returns the XDR spec for the Token contract.
+    pub const fn spec_xdr() -> [u8; TOKEN_SPEC_XDR_LEN] {
+        let input = TOKEN_SPEC_XDR_INPUT;
+        // Concatenate all XDR for each item that makes up the token spec.
+        let mut output = [0u8; TOKEN_SPEC_XDR_LEN];
+        let mut input_i = 0;
+        let mut output_i = 0;
+        while input_i < input.len() {
+            let subinput = input[input_i];
+            let mut subinput_i = 0;
+            while subinput_i < subinput.len() {
+                output[output_i] = subinput[subinput_i];
+                output_i += 1;
+                subinput_i += 1;
+            }
+            input_i += 1;
+        }
+
+        // Check that the numbers of bytes written is equal to the number of bytes
+        // expected in the output.
+        if output_i != output.len() {
+            panic!("unexpected output length",);
+        }
+
+        output
+    }
+}
+
 /// Interface for admin capabilities for Token contracts, such as the Stellar
 /// Asset Contract.
 #[contractspecfn(name = "StellarAssetSpec", export = false)]
 #[contractclient(crate_path = "crate", name = "StellarAssetClient")]
 pub trait StellarAssetInterface {
+    /// Returns the allowance for `spender` to transfer from `from`.
+    ///
+    /// The amount returned is the amount that spender is allowed to transfer
+    /// out of from's balance. When the spender transfers amounts, the allowance
+    /// will be reduced by the amount transferred.
+    ///
+    /// # Arguments
+    ///
+    /// * `from` - The address holding the balance of tokens to be drawn from.
+    /// * `spender` - The address spending the tokens held by `from`.
+    fn allowance(env: Env, from: Address, spender: Address) -> i128;
+
+    /// Set the allowance by `amount` for `spender` to transfer/burn from
+    /// `from`.
+    ///
+    /// The amount set is the amount that spender is approved to transfer out of
+    /// from's balance. The spender will be allowed to transfer amounts, and
+    /// when an amount is transferred the allowance will be reduced by the
+    /// amount transferred.
+    ///
+    /// # Arguments
+    ///
+    /// * `from` - The address holding the balance of tokens to be drawn from.
+    /// * `spender` - The address being authorized to spend the tokens held by
+    ///   `from`.
+    /// * `amount` - The tokens to be made available to `spender`.
+    /// * `expiration_ledger` - The ledger number where this allowance expires. Cannot
+    ///    be less than the current ledger number unless the amount is being set to 0.
+    ///    An expired entry (where expiration_ledger < the current ledger number)
+    ///    should be treated as a 0 amount allowance.
+    ///
+    /// # Events
+    ///
+    /// Emits an event with topics `["approve", from: Address,
+    /// spender: Address], data = [amount: i128, expiration_ledger: u32]`
+    fn approve(env: Env, from: Address, spender: Address, amount: i128, expiration_ledger: u32);
+
+    /// Returns the balance of `id`.
+    ///
+    /// # Arguments
+    ///
+    /// * `id` - The address for which a balance is being queried. If the
+    ///   address has no existing balance, returns 0.
+    fn balance(env: Env, id: Address) -> i128;
+
+    /// Transfer `amount` from `from` to `to`.
+    ///
+    /// # Arguments
+    ///
+    /// * `from` - The address holding the balance of tokens which will be
+    ///   withdrawn from.
+    /// * `to` - The address which will receive the transferred tokens.
+    /// * `amount` - The amount of tokens to be transferred.
+    ///
+    /// # Events
+    ///
+    /// Emits an event with topics `["transfer", from: Address, to: Address],
+    /// data = amount: i128`
+    fn transfer(env: Env, from: Address, to: Address, amount: i128);
+
+    /// Transfer `amount` from `from` to `to`, consuming the allowance that
+    /// `spender` has on `from`'s balance. Authorized by spender
+    /// (`spender.require_auth()`).
+    ///
+    /// The spender will be allowed to transfer the amount from from's balance
+    /// if the amount is less than or equal to the allowance that the spender
+    /// has on the from's balance. The spender's allowance on from's balance
+    /// will be reduced by the amount.
+    ///
+    /// # Arguments
+    ///
+    /// * `spender` - The address authorizing the transfer, and having its
+    ///   allowance consumed during the transfer.
+    /// * `from` - The address holding the balance of tokens which will be
+    ///   withdrawn from.
+    /// * `to` - The address which will receive the transferred tokens.
+    /// * `amount` - The amount of tokens to be transferred.
+    ///
+    /// # Events
+    ///
+    /// Emits an event with topics `["transfer", from: Address, to: Address],
+    /// data = amount: i128`
+    fn transfer_from(env: Env, spender: Address, from: Address, to: Address, amount: i128);
+
+    /// Burn `amount` from `from`.
+    ///
+    /// Reduces from's balance by the amount, without transferring the balance
+    /// to another holder's balance.
+    ///
+    /// # Arguments
+    ///
+    /// * `from` - The address holding the balance of tokens which will be
+    ///   burned from.
+    /// * `amount` - The amount of tokens to be burned.
+    ///
+    /// # Events
+    ///
+    /// Emits an event with topics `["burn", from: Address], data = amount:
+    /// i128`
+    fn burn(env: Env, from: Address, amount: i128);
+
+    /// Burn `amount` from `from`, consuming the allowance of `spender`.
+    ///
+    /// Reduces from's balance by the amount, without transferring the balance
+    /// to another holder's balance.
+    ///
+    /// The spender will be allowed to burn the amount from from's balance, if
+    /// the amount is less than or equal to the allowance that the spender has
+    /// on the from's balance. The spender's allowance on from's balance will be
+    /// reduced by the amount.
+    ///
+    /// # Arguments
+    ///
+    /// * `spender` - The address authorizing the burn, and having its allowance
+    ///   consumed during the burn.
+    /// * `from` - The address holding the balance of tokens which will be
+    ///   burned from.
+    /// * `amount` - The amount of tokens to be burned.
+    ///
+    /// # Events
+    ///
+    /// Emits an event with topics `["burn", from: Address], data = amount:
+    /// i128`
+    fn burn_from(env: Env, spender: Address, from: Address, amount: i128);
+
+    /// Returns the number of decimals used to represent amounts of this token.
+    ///
+    /// # Panics
+    ///
+    /// If the contract has not yet been initialized.
+    fn decimals(env: Env) -> u32;
+
+    /// Returns the name for this token.
+    ///
+    /// # Panics
+    ///
+    /// If the contract has not yet been initialized.
+    fn name(env: Env) -> String;
+
+    /// Returns the symbol for this token.
+    ///
+    /// # Panics
+    ///
+    /// If the contract has not yet been initialized.
+    fn symbol(env: Env) -> String;
+
     /// Sets the administrator to the specified address `new_admin`.
     ///
     /// # Arguments
@@ -305,13 +499,13 @@ pub trait StellarAssetInterface {
     fn clawback(env: Env, from: Address, amount: i128);
 }
 
-/// Spec contains the contract spec of Token contracts, including the general
-/// interface, as well as the admin interface, such as the Stellar Asset
-/// Contract.
+/// Spec contains the contract spec of the Stellar Asset Contract.
+///
+/// The Stellar Asset Contract is a superset of the Token Contract.
 #[doc(hidden)]
 pub struct StellarAssetSpec;
 
-pub(crate) const SPEC_XDR_INPUT: &[&[u8]] = &[
+pub(crate) const STELLAR_ASSET_SPEC_XDR_INPUT: &[&[u8]] = &[
     &StellarAssetSpec::spec_xdr_allowance(),
     &StellarAssetSpec::spec_xdr_authorized(),
     &StellarAssetSpec::spec_xdr_approve(),
@@ -330,14 +524,14 @@ pub(crate) const SPEC_XDR_INPUT: &[&[u8]] = &[
     &StellarAssetSpec::spec_xdr_transfer_from(),
 ];
 
-pub(crate) const SPEC_XDR_LEN: usize = 6456;
+pub(crate) const STELLAR_ASSET_SPEC_XDR_LEN: usize = 6456;
 
 impl StellarAssetSpec {
     /// Returns the XDR spec for the Token contract.
-    pub const fn spec_xdr() -> [u8; SPEC_XDR_LEN] {
-        let input = SPEC_XDR_INPUT;
+    pub const fn spec_xdr() -> [u8; STELLAR_ASSET_SPEC_XDR_LEN] {
+        let input = STELLAR_ASSET_SPEC_XDR_INPUT;
         // Concatenate all XDR for each item that makes up the token spec.
-        let mut output = [0u8; SPEC_XDR_LEN];
+        let mut output = [0u8; STELLAR_ASSET_SPEC_XDR_LEN];
         let mut input_i = 0;
         let mut output_i = 0;
         while input_i < input.len() {