In part 1 we went over how to find out the entry point for the code you are securing and how to map out your way through.
In this part, I’m going to share with you how I document my ideas to allow me rapidly build and use logical models of how the protocol work.
I call this function documentation, although I also do that for structs and other datatypes.
The essence of this method is to
1 - document the function parameters
2 - document the function access control
3 - document the business logic of the function in your own words ( this is important )
For instance, let's consider the infamous function
To document this function I will do the following :
For the parameters I label the use of each of them, and whether it is usually user-supplied or not. In our case, if you are dealing with an NFT, all the parameters are user supplied.
However, this function might be called in a different context, where the parameters are derived from the calling function.
The main reason for flagging user-supplied parameters is that they are an excellent way for the user to break things. If these values are not sufficiently checked or the user passes in an unhandled value, they can easily break the flow.
There is another major benefit to this specific format, when this function is called, say from an inheriting contract, VScode shows me this documentation when I hover over the function name.
Here is what it looks like:
I can't stress how powerful this is!
When I’m going through a flow that involves this function, I can simply hover over it to regain all my knowledge of what this function does. This allows me to quickly build up mental models of how this flow is structured.
It also allows me to build up threat vectors to add to my threat modeling, these laters undergo further development, and some of them mature into powerful PoC!
For instance, suppose I was assessing the
safeTransferFrom flow, and I wanted to quickly remember what the function
Instead of going to the definition ( which can break my train of thought), I simply hover over it and see my documentation:
See how this amazingly speeds things up!
It is also a good idea to do that for complex data types, like structs with lots of fields. This will allow you to hover over the struct, in the function parameters for instance, and see all the fields with what they are supposed to do!
Give this method a trial in your next assessment and let me know what you think!