feat(sdk): Add MultiLocation override feature ⛓️

[michaeldev5]

This PR request adds a feature to allow integration of MultiLocation objects in the transfer process. Instead of passing currency, address and destination traditionally, you can pass a MultiLocation object instead which will override default behaviour. This brings flexibility and customization to our SDK.

The Builder methods to(), currency() and address() have been modified to accept a MultiLocation type.

The MultiLocation object has the following structure:

export interface TMultiLocation {
  parents: StringOrNumber
  interior: Junctions
}

The interior has to have one of the following keys: X1, X2, X3, X4, X5, X6, X7, X8. The Junctions enum can represent zero to eight steps down the hierarchy.

When using X1 ,pass the object as the value: X1: {}, otherwise use array X2: [].

Then in the object or array we can specify the junction type. We can only choose as many junctions as the number after X says. Otherwise a TS error will be thrown. These are available junctions:

interface JunctionParachain {
  Parachain: StringOrNumber
}

interface JunctionAccountId32 {
  AccountId32: {
    network: NetworkId
    id: HexString
  }
}

interface JunctionAccountIndex64 {
  AccountIndex64: {
    network: NetworkId
    index: StringOrNumber
  }
}

interface JunctionAccountKey20 {
  AccountKey20: {
    network: NetworkId
    key: HexString
  }
}

interface JunctionPalletInstance {
  PalletInstance: StringOrNumber
}

interface JunctionGeneralIndex {
  GeneralIndex: StringOrNumber
}

interface JunctionGeneralKey {
  GeneralKey: {
    length: StringOrNumber
    data: HexString
  }
}

interface JunctionOnlyChild {
  OnlyChild: string
}

interface JunctionPlurality {
  Plurality: {
    id: BodyId
    part: BodyPart
  }
}

interface JunctionGlobalConsensus {
  GlobalConsensus: NetworkId
}

An example of overriding address in ParaToPara call:

return Builder(api)
        .from(from)
        .to(to)
        .currency(currency)
        .amount(amount)
        .address({
          parents: 1,
          interior: {
            X2: [
              {
                Parachain: 200,
              },
              {
                GeneralIndex: 0,
              },
            ],
          },
        })
        .build();

We can do the same with currency() and to()(destination).

An example of overriding currency in ParaToPara call:

return Builder(api)
        .from(from)
        .to(to)
        .currency({
          parents: 1,
          interior: {
            X2: [
              { PalletInstance: '50' }, { GeneralIndex: currencyId }
            ],
          },
        })
        .amount(amount)
        .address(address)
        .build();

An example of overriding destination in ParaToPara call:

return Builder(api)
        .from(from)
        .to({
          parents: 1,
          interior: {
            X1: {
            Parachain: nodeId
          }
          },
        })
        .currency(currency)
        .amount(amount)
        .address(address)
        .build();

However when the origin Parachain uses XTokens or XTransfer pallet MultiLocation destinations are not supported. In this case you need to use the address multilocation for both destination and address. Here is an example of such MultiLocation:

{
    parents: 1,
    interior: {
        X2: [{
                Parachain: nodeId
            },
            {
                AccountId32: {
                    network: 'any',
                    id: createAccountId(api, recipientAddress)
                }
            }
        ]
    }
}

For PolkadotXCM you can use all 3 options separately.

[netlify]

✅ Deploy Preview for light-spell ready!

Name	Link
🔨 Latest commit	1326a0d
🔍 Latest deploy log	https://app.netlify.com/sites/light-spell/deploys/6619a97f4d6e790008918435
😎 Deploy Preview	https://deploy-preview-199--light-spell.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 97 Accessibility: 83 Best Practices: 100 SEO: 69 PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify]

✅ Deploy Preview for poetic-heliotrope-212f1c ready!

Name	Link
🔨 Latest commit	1326a0d
🔍 Latest deploy log	https://app.netlify.com/sites/poetic-heliotrope-212f1c/deploys/6619a97f53a319000709fa0e
😎 Deploy Preview	https://deploy-preview-199--poetic-heliotrope-212f1c.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.