SCDS - Smart Contract Diagram Standard

Transcript

Okay. >> All right. I think uh we're cooking with gas. There we go. Uh hi everyone. My name is George. I'm here from Consensus Diligence to talk to you guys a little bit about diagrams in smart contracts and smart contract systems. So of course the natural why, right? What's the problem? Why are we doing this? Um naturally here we as security people we really understand um the um usefulness of a good diagram. We've all I'm sure made many diagrams for our audits and our reports. But unfortunately nowadays it's not such a good um they're not in such a good state in our industry. Often times you get

some pretty good maybe mediocre maybe a little bit better diagrams made by project teams within their documentation. But once you get into kind of like more thirdparty assessment, audit assessment, um, integrated uh, team assessment, you get something kind of like this, which is not of course a real diagram. It's something more of a parody of a few diagrams I've seen out there in some audit reports. Uh, which is where the engineer got really caught up in the technical details in the process. And I'm sure it was useful for the engineer to create the diagram as he was or she was creating it. But for a reader, for somebody who was reading the report, this is just too confusing, too much information. And uh I you would just be confused and clueless. And in fact there

on the right side is actually one of the diagrams I made very very recently and that's where I knew I had to do something about this problem because I was trying to convey that a single contract is very important in the system and then in the end it just ended up being like spaghetti of arrows which is not so good. To fix this I went ahead and asked a bunch of developers and auditors that I know in the space what did they do? how do they address diagrams in their reports in their assessments and um I also looked into what do they do in the greater software industry um like in general uh there are quite a few takeaways the three big ones that I saw were that even if the diagrams don't end up

becoming this way the engineer always tries to make a diagram for one single specific use case so it could be a general architectural review it could be data flow control flow flow, font flow. Um, even if it doesn't end up being that way, but the intention is usually to do for something specific. It is also true that even if the technical detail the level ends up being very varied in the diagram, they usually are intended to be either super detailed or general. Um, kind of like not a mix of a situation, but one type of degree. And something that is quite new and quite interesting is a lot of people have expressed interest in making diagrams in a more

automated manner using AIS uh AI agents excuse me and maybe even have those um diagrams be digestible by those machines. uh not surprisingly other industries uh that use software have also talked about these things and one of the interesting things that you get as a takeaway in those frameworks there is that whenever you make diagrams or diagram standards or guidelines you should be opinionated you should give guidelines because engineers kind of get caught up in their technical details and they really need visual guidelines so with that I have uh done some work and I created a CDS I've made a proposal on the Ethereum magicians forum uh that and it also has a bigger draft of my um actual standard there. If you're

interested to view it and give feedback, I would really appreciate it. Overall, uh it is a minimal machine readable standard for diagrams that does two big things. A, it gives some opinionated rules for how to make diagrams with specific types of edges and nodes. And number two, and that's very interesting, especially today, is I do also provide rules for a canonical JSON encoding of that semantic model. And so I want to focus on uh two things. Number one is that what I just mentioned is the JSON encoding of a model. It's super duper simple. I mean again it's just diagram uh and kind of it's its internals over there. Uh the important parts that I've created or added there is more things

like what kinds what kinds of nodes there are, what kind of edges there are that are more specific to our industry and our flavors. And um I think this if any of you have ever done any smart contract parsing with like the JavaScript solidity parser for example, you'll see that this is just a much more general version of what you get out from there. So this could really indeed be something that's created from AI and contract artifacts and then summarized by maybe uh AI agents and create something like that which then can of course be uh displayed and rendered in other um tools. And number two that I think uh I will definitely be using and I suggest a lot of people to start using

is to start making more leveled and refined diagrams which is where instead of making one giant diagram with too many things on it you just make a simpler one and then you focus on a specific aspect of it and then you go further and further and further so that you don't have more than like seven or nine concepts or objects on a diagram at any given time. So please if you're interested in any of this uh if you think this is useful feel free to leave any comments on my Ethereum magicians post and uh diagram away. Thank you. >> Thank you.