Post-W3F API changes: signWithAccount, getPrimaryDotNsName, certifications, product keys

[filvecchiato]

Summary

Four API surface changes for the post-W3F milestone.

1. Rename signWithLegacyAccount → signWithAccount

signWithAccount accepts any AccountId that the UA can attempt to sign with and that has been returned by TrUAPI into the current product on the current device. This generalises the legacy-only signing surface to cover all account types.

2. Introduce getPrimaryDotNsName

Returns a (DotNsNode, AccountId) pair — the product's primary dotNS node (a path into the namespace) and the controlling account. The controlling account should generally be signable via signWithAccount.

3. Introduce a certifications system

A generalisation of the proof-of-control flow currently implemented in the Playground. The certifications system:

1. Allows any two accounts to prove common control (i.e. that the same entity controls both).
2. Supports both public certifications (verifiable by anyone) and private certifications (verifiable only by a designated audience).

4. Move freebie claim account IDs to product keys

Freebie claim account IDs should live under product keys rather than their current location.

[valentinfernandez1]

We should also revise getAccount(), getAccountAlias(), createAccountProof(), createTransaction(), signRaw() and signPayload().

All of these methods require an account to be passed in with the structure:

account: {
    dotNsIdentifier: "truapi-playground.dot",
    derivationIndex: 0,
}

However the host already knows the dotNsIdentifier so passing it as a parameter does not make sense as the host can already resolve it. And passing an invalid one makes it fail. For example if I attempt to call signRaw() on truapi-playground with a dotNsIdentifier to invalidDotNs.dot signing will fail as it's invalid.

Moving forward the product should only send the derivationIndex. For examplegetAccount() would be:

// Before
await truapi.account.getAccount({
  productAccountId: {
    dotNsIdentifier: "truapi-playground.dot",
    derivationIndex: 0,
  },
});

// After
await truapi.account.getAccount({ derivationIndex: 0 });

[valentinfernandez1]

Note: The only reason why I would hold back from merging is if this is intended in the sense that for example productA.dot is intended to be able to access productB.dot internally for any reason.

AFAIK this is not the intended behavior and products should be isolated from each other.

[filvecchiato]

I agree that the default should not need the productAccountId, but there could indeed be instances where the product might want access to the user's other productId, so rather than removing the option to query other accounts, I would work on better permissioning these methods and require user permission to query outside accounts

[valentinfernandez1]

In that case, alongside the RemotePermissions we should add a new Permission like RemoteAccount or ExternalAccount so that users can allow or deny access to those external accounts.

And have getAccount() be the default and maybe add a getExternalAccount() to obtain accounts from other products. Same for every other method like signTransaction() (add a mirror method signTransactionExternalAccount(), assuming of course that we want to allow products to sign with external accounts. We are just providing the ability to do it but signing might be a more delicate topic).

[valentinfernandez1]

Since this might require its own discussion I will move it to a new issue so that this can focus on your initial comment