|
1 | 1 | --- |
2 | 2 | title: System Decomposition |
3 | | ---- |
4 | | - |
5 | | -# System Decomposition |
6 | | ---- |
7 | | - |
8 | | -## Implementing Systems |
9 | | - |
10 | | -In order to make it easier to decouple functionality into systems, the Filecoin Protocol assumes |
11 | | -a set of functionality available to all systems. This functionality can be achieved by implementations |
12 | | -in a variety of ways, and should take the guidance here as a recommendation (SHOULD). |
13 | | - |
14 | | -### System Requirements |
15 | | - |
16 | | -All Systems, as defined in this document, require the following: |
17 | | - |
18 | | -- **Repository:** |
19 | | - - **Local `IpldStore`.** Some amount of persistent local storage for data structures (small structured objects). |
20 | | - Systems expect to be initialized with an IpldStore in which to store data structures they expect to persist across crashes. |
21 | | - - **User Configuration Values.** A small amount of user-editable configuration values. |
22 | | - These should be easy for end-users to access, view, and edit. |
23 | | - - **Local, Secure `KeyStore`.** A facility to use to generate and use cryptographic keys, which MUST remain secret to the |
24 | | - Filecoin Node. Systems SHOULD NOT access the keys directly, and should do so over an abstraction (ie the `KeyStore`) which |
25 | | - provides the ability to Encrypt, Decrypt, Sign, SigVerify, and more. |
26 | | -- **Local `FileStore`.** Some amount of persistent local storage for files (large byte arrays). |
27 | | - Systems expect to be initialized with a FileStore in which to store large files. |
28 | | - Some systems (like Markets) may need to store and delete large volumes of smaller files (1MB - 10GB). |
29 | | - Other systems (like Storage Mining) may need to store and delete large volumes of large files (1GB - 1TB). |
30 | | -- **Network.** Most systems need access to the network, to be able to connect to their counterparts in other Filecoin Nodes. |
31 | | - Systems expect to be initialized with a `libp2p.Node` on which they can mount their own protocols. |
32 | | -- **Clock.** Some systems need access to current network time, some with low tolerance for drift. |
33 | | - Systems expect to be initialized with a Clock from which to tell network time. Some systems (like Blockchain) |
34 | | - require very little clock drift, and require _secure_ time. |
35 | | - |
36 | | -For this purpose, we use the `FilecoinNode` data structure, which is passed into all systems at initialization: |
37 | | - |
38 | | -{{< embed src="../../systems/filecoin_nodes/node_base/filecoin_node.id" lang="go" >}} |
39 | | - |
40 | | -{{< embed src="../../systems/filecoin_nodes/repository/repository_subsystem.id" lang="go" >}} |
41 | | - |
42 | | -### System Limitations |
43 | | - |
44 | | -Further, Systems MUST abide by the following limitations: |
45 | | - |
46 | | -- **Random crashes.** A Filecoin Node may crash at any moment. Systems must be secure and consistent through crashes. |
47 | | - This is primarily achived by limiting the use of persistent state, persisting such state through Ipld data structures, |
48 | | - and through the use of initialization routines that check state, and perhaps correct errors. |
49 | | -- **Isolation.** Systems must communicate over well-defined, isolated interfaces. They must not build their critical |
50 | | - functionality over a shared memory space. (Note: for performance, shared memory abstractions can be used to power |
51 | | - IpldStore, FileStore, and libp2p, but the systems themselves should not require it.) This is not just an operational |
52 | | - concern; it also significantly simplifies the protocol and makes it easier to understand, analyze, debug, and change. |
53 | | -- **No direct access to host OS Filesystem or Disk.** Systems cannot access disks directly -- they do so over the FileStore |
54 | | - and IpldStore abstractions. This is to provide a high degree of portability and flexibility for end-users, especially |
55 | | - storage miners and clients of large amounts of data, which need to be able to easily replace how their Filecoin Nodes |
56 | | - access local storage. |
57 | | -- **No direct access to host OS Network stack or TCP/IP.** Systems cannot access the network directly -- they do so over the |
58 | | - libp2p library. There must not be any other kind of network access. This provides a high degree of portability across |
59 | | - platforms and network protocols, enabling Filecoin Nodes (and all their critical systems) to run in a wide variety of |
60 | | - settings, using all kinds of protocols (eg Bluetooth, LANs, etc). |
61 | | - |
62 | | - |
63 | | -## What are systems? How do they work? |
64 | | ---- |
65 | | - |
66 | | -Filecoin decouples and modularizes functionality into loosely-joined `systems`. |
67 | | -Each system adds significant functionality, usually to achieve a set of important and tightly related goals. |
68 | | - |
69 | | -For example, the Blockchain System provides structures like Block, Tipset, and Chain, and provides functionality |
70 | | -like Block Sync, Block Propagation, Block Validation, Chain Selection, and Chain Access. This is |
71 | | -separated from the Files, Pieces, Piece Preparation, and Data Transfer. Both of these systems are separated from |
72 | | -the Markets, which provide Orders, Deals, Market Visibility, and Deal Settlement. |
73 | | - |
74 | | -### Why is System decoupling useful? |
75 | | - |
76 | | -This decoupling is useful for: |
77 | | - |
78 | | -- **Implementation Boundaries:** it is possible to build implementations of Filecoin that only implement a |
79 | | - subset of systems. This is especially useful for _Implementation Diversity_: we want many implementations |
80 | | - of security critical systems (eg Blockchain), but do not need many implementations of Systems that can be |
81 | | - decoupled. |
82 | | -- **Runtime Decoupling:** system decoupling makes it easier to build and run Filecoin Nodes that isolate |
83 | | - Systems into separate programs, and even separate physical computers. |
84 | | -- **Security Isolation:** some systems require higher operational security than others. System decoupling allows |
85 | | - implementations to meet their security and functionality needs. A good example of this is separating Blockchain |
86 | | - processing from Data Transfer. |
87 | | -- **Scalability:** systems, and various use cases, may drive different performance requirements for different opertators. |
88 | | - System decoupling makes it easier for operators to scale their deployments along system boundaries. |
89 | | - |
90 | | - |
91 | | -### Filecoin Nodes don't need all the systems |
92 | | - |
93 | | -Filecoin Nodes vary significantly, and do not need all the systems. |
94 | | -Most systems are only needed for a subset of use cases. |
95 | | - |
96 | | -For example, the Blockchain System is required for synchronizing the chain, participating in secure consensus, |
97 | | -storage mining, and chain validation. |
98 | | -Many Filecoin Nodes do not need the chain and can perform their work by just fetching content from the latest |
99 | | -StateTree, from a node they trust. |
100 | | - |
101 | | -Note: Filecoin does not use the "full node" or "light client" terminology, in wide use in Bitcoin and other blockchain |
102 | | -networks. In filecoin, these terms are not well defined. It is best to define nodes in terms of their capabilities, |
103 | | -and therefore, in terms of the Systems they run. For example: |
104 | | - |
105 | | -- **Chain Verifier Node:** Runs the Blockchain system. Can sync and validate the chain. Cannot mine or produce blocks. |
106 | | -- **Client Node:** Runs the Blockchain, Market, and Data Transfer systems. Can sync and validate the chain. Cannot mine or produce blocks. |
107 | | -- **Retrieval Miner Node:** Runs the Market and Data Transfer systems. Does not need the chain. Can make Retrieval Deals |
108 | | - (Retrieval Provider side). Can send Clients data, and get paid for it. |
109 | | -- **Storage Miner Node:** Runs the Blockchain, Storage Market, Storage Mining systems. Can sync and validate the chain. |
110 | | - Can make Storage Deals (Storage Provider side). Can seal stored data into sectors. Can acquire |
111 | | - storage consensus power. Can mine and produce blocks. |
112 | | - |
113 | | -### Separating Systems |
114 | | - |
115 | | -> How do we determine what functionality belongs in one system vs another? |
116 | | -
|
117 | | -Drawing boundaries between systems is the art of separating tightly related functionality from unrelated parts. |
118 | | -In a sense, we seek to keep tightly integrated components in the same system, and away from other unrelated |
119 | | -components. This is sometimes straightforward, the boundaries naturally spring from the data structures or |
120 | | -functionality. For example, it is straightforward to observe that Clients and Miners negotiating a deal |
121 | | -with each other is very unrelated to VM Execution. |
122 | | - |
123 | | -Sometimes this is harder, and it requires detangling, adding, or removing abstractions. For |
124 | | -example, the `StoragePowerActor` and the `StorageMarketActor` were a single `Actor` previously. This caused |
125 | | -a large coupling of functionality across `StorageDeal` making, the `StorageMarket`, markets in general, with |
126 | | -Storage Mining, Sector Sealing, PoSt Generation, and more. Detangling these two sets of related functionality |
127 | | -requried breaking apart the one actor into two. |
128 | | - |
129 | | -### Decomposing within a System |
130 | | - |
131 | | -Systems themselves decompose into smaller subunits. These are sometimes called "subsystems" to avoid confusion |
132 | | -with the much larger, first-class Systems. Subsystems themselves may break down further. The naming here is not |
133 | | -strictly enforced, as these subdivisions are more related to protocol and implementation engineering concerns |
134 | | -than to user capabilities. |
| 3 | +weight: 6 |
| 4 | +bookCollapseSection: true |
| 5 | +--- |
0 commit comments