[SEC-F29] Incomplete design documentation

[krpeacock]

Observation

The design gives a high level description and the interface specification. However, it does not cover the following (this may not be a complete list):

• Any limitations (also wrt. security) should be clearly listed in the doc.
• It is not clear from the design what data is stored on the canister.
• Even though the interface is specified, it is not clear from the design what exactly the individual methods do: what are the preconditions? Who is authorized to perform the operation? How do they modify the state? What do they return?
• It is not documented what kinds of subaccounts the canister uses and what they are for.
• The way the funds flow through invoicing is not documented. It would be useful to have a description of how the money flows through different accounts (creation, verification, refund, transfer). Maybe our notes could help.
• The "Basic Payment Flow ( hypothetical )” section should be updated. This should not be hypothetical

Risk Description

Writing a financial dApp where most functionality is only described by the code itself is risky:

• The lack of design documentation makes it hard to judge (e.g. in security reviews) if the code behaves as intended, because the intended behavior is not made explicit and can only be inferred from the code.
• It is hard to spot design issues
• One cannot understand the app (e.g. for people using it) and its guarantees without reading the code.

Recommendations

Extend the design document and in particular address the points given here.