Ensure MultiLocation always has a canonical representation

[KiChjang]

Fixes #3312.

The API for MultiLocation is changed slightly as a result of eliminating the parent junction:

Firstly, all push operations have been split into a parent and non-parent counterpart.

Secondly, take operations that take from the front are denoted with non_parent to indicate that we do not modify the parent count.

Thirdly, the Junctions enum notably does not have any methods that can cause an overflow. pushed_with and pushed_front_with are left intact however, because they take ownership and there is no way to obtain ownership of a Junctions from a MultiLocation.

[apopiak]

Not sure this PR is the right context, but before we're introducing a new XCM version I would like to raise an issue I see with v0:
I see a difference between NetworkId and MultiAsset on the one hand and other enums/"identifiers" like MultiLocation or BodyPart. The latter separate the identifying and filtering parts. Identifying is done by the enum instance (e.g. a multilocation might be X2(Parachain(1), GeneralIndex(42))) while filtering is done in the XCM implementation (e.g. the IsTeleporter filter). This IMO is a good pattern.
NetworkId and MultiAsset combine an identifying function with a filter function within the enum which leads to non-filtering code having to manage the case when we get MultiAsset::AllFungible even though that is not its purpose. I think we should avoid this in v1 and separate filtering and identifying completely.

Opened #3409 if you don't want to discuss this here.

[KiChjang]

@apopiak Yeah I agree, this PR is probably not the best place to discuss things that are not related to the MultiLocation. A new XCM version is created simply because it is easier to accommodate changes to the MultiLocation types. But I do think that some changes ought to be bundled together if we were to introduce a new version.

[shawntabrizi]

not having looked at this PR at all, we should make the evaluation whether maintaining and supporting 2 xcm versions at this point is better than introducing a breaking change. It feels to me, that 2 versions of XCM at this point will be more technical debt than it is worth

[gavofyork]

Good stuff, but I'd prefer not to need to create XCM v1 on the back of this, when we can very easily just have a custom encoding:

/// A single item in a path to describe the relative location of a consensus system.
///
/// Each item assumes a pre-existing location as its context and is defined in terms of it.
///
/// Note for this to encode correctly within v0 XCM, the `parents` value plus the `junctions.len)` must be no greater
/// than 255.
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Debug)]
pub struct MultiLocation {
	/// The number of ancestor levels to ascend to find the exterior context. If zero, then it's not an exterior
	/// location.
	pub parents: u8,
	/// The interior components of the exterior context.
	pub interior: Junctions,
}

impl Encode for MultiLocation {
	fn encode_to<T: Output + ?Sized>(&self, output: &mut T) {
		// 255 items max, but we cannot return an error, so we ap silently.
		let parents = self.parents.min(255.saturating_sub(self.junctions.len()) as u8);
		let count = parents.saturating_add(junctions.len());
		output.push_byte(count);
		for _ in 0..parents {
			output.push_byte(0);
		}
		for j in self.interior.iter() {
			j.encode_to(output)
		}
	}
}

impl Decode for MultiLocation {
	fn decode<I: Input>(input: &mut I) -> Result<Self, parity_scale_codec::Error> {
		let count = input.read_byte()?;
		let mut parents = 0u8;
		let mut interior = Junctions::Null;
		for i in 0..count {
			let b = output.read_byte()?;
			if b == 0 {
				if i > s.parents {
					// this would imply that there has been at least one non-parent junction, which further implies
					// that this is non-canonical. we bail.
					return Err(parity_scale_codec::Error::from("Parent after non-Parent forbidden"))
				}
				parents += 1;
			} else {
				interior.push(Junction::decode(&mut &[b])?)
					.map_err(|_| parity_scale_codec::Error::from("Interior too long"))?;
			}
		}
		Ok(MultiLocation { parents, interior })
	}
}

This custom Encode/Decode together with a #[codec::index = 1] on the first item in Junction should obviate the need to bump the XCM version.

[gavofyork]

Minor rework, but overall good.

[KiChjang]

bot merge

[ghost]

Trying merge.

[KiChjang]