c41baa9bc8
* Overview of keepers in object capability model (OCM) * Updates to the spec, making clarifications * Create a sequence diagram of a (fresh) delegation * Misc notes, not yet decided where to put them * Description of the shares abstraction in validators * Model all keeper dependencies and move the UML file to docs * Move and rename delegation sequence diagram * Move shares description * Remove TODO * Diagram touch-ups * Add how consensus power is calculated * remove temp file * Diagram improvements * Describe slashing in more detail * Describe redelegation * Describe unbonding * Delegation updates * Delegation updates * Make a diagram describing overall transaction flow * Add delegation flows for the events of tokens being bonded/unbonding/etc. * Grammar fix * Diagram updates: distinguish alts, remove numbering. * Use groups instead of "func:" participants * Remove unused keepers from dependency diagram * Add title to unbonding diagram * Move keeper dependencies * small doc updates * remove numbers on sequence diagram * !!!WIP EndBlock * Explain "Last"-prefix in storage * Remove `panic` step (they are supposed to never happen) * EndBlock sequence diagram (with TODOs) * Add TODO * More visible TODOs * Remove numbering * Complete EndBlock * Remove numbering * Remove TODOs and update title * add title back * remove endblock seq-diagram * Make power index update conditional on not being jailed * update title * Move files to /docs * Install PlantUML and compile images to png and txt * Use transaction flow in documentation * Use staking UML in staking docs * Clarify uml with inline doc * Add keeper deps diagram to docs * Only produce SVG images Co-authored-by: hjort <> Co-authored-by: Marko <marbar3778@yahoo.com>
2.7 KiB
Object-Capability Model
Intro
When thinking about security, it is good to start with a specific threat model. Our threat model is the following:
We assume that a thriving ecosystem of Cosmos-SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules.
The Cosmos SDK is designed to address this threat by being the foundation of an object capability system.
The structural properties of object capability systems favor modularity in code design and ensure reliable encapsulation in code implementation.
These structural properties facilitate the analysis of some security properties of an object-capability program or operating system. Some of these — in particular, information flow properties — can be analyzed at the level of object references and connectivity, independent of any knowledge or analysis of the code that determines the behavior of the objects.
As a consequence, these security properties can be established and maintained in the presence of new objects that contain unknown and possibly malicious code.
These structural properties stem from the two rules governing access to existing objects:
- An object A can send a message to B only if object A holds a reference to B.
- An object A can obtain a reference to C only if object A receives a message containing a reference to C. As a consequence of these two rules, an object can obtain a reference to another object only through a preexisting chain of references. In short, "Only connectivity begets connectivity."
For an introduction to object-capabilities, see this Wikipedia article.
Ocaps in practice
The idea is to only reveal what is necessary to get the work done.
For example, the following code snippet violates the object capabilities principle:
type AppAccount struct {...}
account := &AppAccount{
Address: pub.Address(),
Coins: sdk.Coins{sdk.NewInt64Coin("ATM", 100)},
}
sumValue := externalModule.ComputeSumValue(account)
The method ComputeSumValue implies a pure function, yet the implied
capability of accepting a pointer value is the capability to modify that
value. The preferred method signature should take a copy instead.
sumValue := externalModule.ComputeSumValue(*account)
In the Cosmos SDK, you can see the application of this principle in the gaia app.
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.4/simapp/app.go#L249-L273
The following diagram shows the current dependencies between keepers.
Next {hide}
Learn about the runTx middleware {hide}