Add support for additional _muxed and _muxed_id optional fields in Horizon's JSON responses

[2opremio]

TL;DR

Add support for additional _muxed and _muxed_id optional fields in Horizon's JSON responses (available since Horizon 2.4, following what's described in SEP 23). That is:

Anyplace a MuxedAccount appears, if the account is of a multiplexed
type (currently just KEY_TYPE_MUXED_ED2551), two new fields are
added to the JSON.

• Base field name + _muxed is the strkey of the multiplexed account.

• Base field name + _muxed_id is the integer.

For example, given the MuxedAccount
MAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSAAAAAAAAAAE2LP26,
you might get the following fields:

    source_account: GAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSTVY
    source_account_muxed: MAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSAAAAAAAAAAE2LP26
    source_account_muxed_id: 1234

For instance, here's an /operations response with the new fields:

{
  "_links": {
    "self": {
      "href": "https://horizon.stellar.org/operations/?cursor=\u0026limit=10\u0026order=asc"
    },
    "next": {
      "href": "https://horizon.stellar.org/operations/?cursor=33818572492801\u0026limit=10\u0026order=asc"
    },
    "prev": {
      "href": "https://horizon.stellar.org/operations/?cursor=12884905985\u0026limit=10\u0026order=desc"
    }
  },
  "_embedded": {
    "records": [
      {
        "_links": {
          "self": {
            "href": "https://horizon.stellar.org/operations/12884905986"
          },
          "transaction": {
            "href": "https://horizon.stellar.org/transactions/3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889"
          },
          "effects": {
            "href": "https://horizon.stellar.org/operations/12884905986/effects"
          },
          "succeeds": {
            "href": "https://horizon.stellar.org/effects?order=desc\u0026cursor=12884905986"
          },
          "precedes": {
            "href": "https://horizon.stellar.org/effects?order=asc\u0026cursor=12884905986"
          }
        },
        "id": "12884905986",
        "paging_token": "12884905986",
        "transaction_successful": true,
        "source_account": "GAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSTVY",
        "source_account_muxed": "MAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSAAAAAAAAAAE2LP26",
        "source_account_muxed_id": 1234,
        "type": "payment",
        "type_i": 1,
        "created_at": "2015-09-30T17:15:54Z",
        "transaction_hash": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889",
        "asset_type": "native",
        "from": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "from_muxed": "MAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSAAAAAAAAAAE2LP26",
        "from_muxed_id": 1234,
        "to": "GAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSTVY",
        "amount": "99999999959.9999700"
      }
    ]
  }
}   

Note the:

• "source_account_muxed" and "source_account_muxed_id" fields.
• "from_muxed" and "from_muxed_id" fields.

Also, note how, although the XDR destination address of the Payment operation is a Multiplexed Account, there are no to_muxed nor to_muxed_id fields in the response. This simply means that the XDR representation of the destination address is of type KEY_TYPE_ED25519 and not KEY_TYPE_MUXED_ED2551.

Exhaustive list of new fields

• transactions objects: "account_muxed", "account_muxed_id", "fee_account_muxed" and "fee_account_muxed_id".
• operation objects: source_account_muxed and source_account_muxed_id. Additional fields depending on the operation type:
  • "create_account" operation: "funder_muxed", "funder_muxed_id".
  • "payment", "path_payment_strict_receive" and "path_payment_strict_send" operations: from_muxed, from_muxed_id, to_muxed and to_muxed_id.
  • "change_trust" operation: "trustor_muxed" and "trustor_muxed_id".
  • "allow_trust" operation: "trustee_muxed" and "trustee_muxed_id".
  • "account_merge" operation: "account_muxed", "account_muxed_id", "into_muxed", and "into_muxed_id".
  • "claim_claimable_balance" operation: "claimant_muxed" and "claimant_muxed_id".
  • "end_sponsoring_future_reserves" operation: "begin_sponsor_muxed", "begin_sponsor_muxed_id".
  • "clawback" operation: "from_muxed", "from_muxed_id".
• effect objects: "account_muxed", "account_muxed_id". Additional fields depending on the effect type:
  • "trade" effect: "seller_muxed" and "seller_muxed_id".

Reference implementation

You can use the Go SDK implementation as a reference:

• stellar/go#3603
• stellar/go#3610
• stellar/go#3626

[2opremio]

Update: the representation of "..._muxed_id" field values changes to string

As explained at stellar/go#3714 , Horizon has changed the representation of "..._muxed_id" fields from integer to string due to Javascript's difficulty to handle 64-bit integers.

The example we used in the description above now becomes:

{
  "_links": {
    "self": {
      "href": "https://horizon.stellar.org/operations/?cursor=\u0026limit=10\u0026order=asc"
    },
    "next": {
      "href": "https://horizon.stellar.org/operations/?cursor=33818572492801\u0026limit=10\u0026order=asc"
    },
    "prev": {
      "href": "https://horizon.stellar.org/operations/?cursor=12884905985\u0026limit=10\u0026order=desc"
    }
  },
  "_embedded": {
    "records": [
      {
        "_links": {
          "self": {
            "href": "https://horizon.stellar.org/operations/12884905986"
          },
          "transaction": {
            "href": "https://horizon.stellar.org/transactions/3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889"
          },
          "effects": {
            "href": "https://horizon.stellar.org/operations/12884905986/effects"
          },
          "succeeds": {
            "href": "https://horizon.stellar.org/effects?order=desc\u0026cursor=12884905986"
          },
          "precedes": {
            "href": "https://horizon.stellar.org/effects?order=asc\u0026cursor=12884905986"
          }
        },
        "id": "12884905986",
        "paging_token": "12884905986",
        "transaction_successful": true,
        "source_account": "GAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSTVY",
        "source_account_muxed": "MAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSAAAAAAAAAAE2LP26",
        "source_account_muxed_id": "1234",
        "type": "payment",
        "type_i": 1,
        "created_at": "2015-09-30T17:15:54Z",
        "transaction_hash": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889",
        "asset_type": "native",
        "from": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
        "from_muxed": "MAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSAAAAAAAAAAE2LP26",
        "from_muxed_id": "1234",
        "to": "GAQAA5L65LSYH7CQ3VTJ7F3HHLGCL3DSLAR2Y47263D56MNNGHSQSTVY",
        "amount": "99999999959.9999700"
      }
    ]
  }
} 

Note how "source_account_muxed_id": 1234, changes to "source_account_muxed_id": "1234", and how "from_muxed_id": 1234, changes to "from_muxed_id": "1234",.

This change was incorporated to Horizon 2.5.1 onwards (although the use of Horizon >=2.5.2 is recommended at this point due to a bug found in 2.5.1).

I apologize for the inconvenience caused by this (we should had caught this problem earlier).