diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 8800292cb..482826ba6 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -110,4 +110,7 @@ ** xref:release-notes:0.6.22-rn.adoc[0.6.22] ** xref:release-notes:0.6.21-rn.adoc[0.6.21] ** xref:release-notes:0.6.20-rn.adoc[0.6.20] -** link:https://github.com/dfinity/sdk/releases[Release history] \ No newline at end of file +** link:https://github.com/dfinity/sdk/releases[Release history] + +.xref:ic-protocol:icp-glossary.adoc[Internet Computer Protocol] +** xref:ic-protocol:icp-glossary.adoc[Glossary] \ No newline at end of file diff --git a/modules/developers-guide/pages/glossary.adoc b/modules/developers-guide/pages/glossary.adoc index 5b1cc3c45..c30d46a52 100644 --- a/modules/developers-guide/pages/glossary.adoc +++ b/modules/developers-guide/pages/glossary.adoc @@ -8,29 +8,140 @@ [[g-actor]] actor:: - An actor is a special kind of object in modern programming languages that processes messages in an isolated state, enabling them to be handled remotely and asynchronously. +An actor is a special kind of object in modern programming languages that processes messages in an isolated state, enabling them to be handled remotely and asynchronously. +//# tag::g-app-canister[] +[[g-app-canister]] +application canister:: +A distributed application written by third-party developers or organizations that has been compiled into a WebAssembly (wasm) module and deployed as a canister on the <> platform. ++ +This terminology is sometimes used to distinguish between user-facing programs deployed as <> and system management services deployed as <>. +However, because an application’s functions might be contained within a single canister or split into multiple canisters—depending on design and implementation decisions made by the application developer—you'll most often find **application** used to describe a software feature set or <> used to describe a deployed computational unit. ++ +Applications and canisters provide services that can be accessed directly by users or accessed by other applications deployed in other canisters. +//# end::g-app-canister[] + +//# tag::g-canister[] [[g-canister]] canister:: - A canister is a conceptual object with a universally-unique identifier and an owner that defines the boundaries of a specific application, service, or micro-site. - A canister encapsulates all of the programming logic, public entry methods, the interface description for the provided message types, and state information for the application, service, or micro-service it describes. +A canister is a conceptual computational unit that consists of both code and state. +Every canister has a unique <> and a <> with permission to manage the canister lifecycle. ++ +A canister encapsulates all of the programming logic, public entry methods, the interface description for the provided message types, and state information for it describes. +After code and state are compiled into a WebAssembly (WASM) module, the application, service, or micro-service can be deployed as canister on the <> and accessed over the network. -[[g-replica]] -replica:: - In the context of the {platform}, a replica refers to the {IC} processes (for example, the `+replica+`, `+nodemanager+`, and other lower-level {IC} protocol processes) running on a physical computer node in the network. - For the {sdk-short-name}, you use the `+dfx start+` and `+dfx stop+` commands to start and stop the `+replica+` process locally to provide a local network for development. +[[g-canister-id]] +canister identifier:: +A globally-unique identifier that is registered on a <> before code is deployed on the <> platform. + +[[g-canister-owner]] +canister owner:: +Deprecated terminology for the person or entity—for example, another canister—that can upgrade or mark a <> as permanent. See <>. +//# end::g-canister[] + +//# tag::g-controller[] +[[g-controller]] +controller:: +The person, organization, or <> that has administrative rights to control operations for another <>. ++ +For example, the controller for a canister can control whether the canister can be upgraded or marked as permanent.+ +The *controller* is a <> property that supports autonomous software operation. +//# end::g-controller[] + +//# tag::g-cycles[] +[[g-cycles]] +cycles:: +Represents the unit of measurement for resources consumed in the form of processing time, memory an application requires for storage, and network bandwidth. The cycles used to pay for resources consumed are held in an account on behalf of a user or an application. ++ +The <> native currency (ICP tokens) can be converted to cycles and transferred to an application account to ensure the application has the resources required to perform its services. +Cycles can also be transferred directly from one application to another. +//# end::g-cycles[] + +//# tag::g-ingress-message[] +[[ingress-message]] +== ingress message +A <> sent by an end-user to <> that is routed through consensus. +//# end::g-ingress-message[] + +//# tag::g-intercanister-call[] +[[g-intercanister-call]] +inter-canister call:: +A <> sent from one <> to another. Inter-canister calls might be initiated on behalf of a user but are distinct from user-initiated <>. ++ +Note that a <> can be an +application-generated <> sent from one <> to another or a system-generated <> sent from one <> to another and that the <> can be on the same or +different <>. +This type of message is also referred to as a *canister-to-canister* message or an *inter-canister message*. +//# end::g-intercanister-call[] +//# tag::g-nns[] +[[g-nns]] +network nervous system (NNS):: +The native governance system for the<> platform. The *network nervous system* provides global configuration and subnet specific information to manage updates to the +replicas, <>, and <> deployed and to handle system change proposals and voting. +//# end::g-nns[] + +//# tag::g-neuron[] +[[g-neuron]] +neuron:: +An entity that can make proposals and vote on proposals related to governance of the <> platform. ++ +To provide the stability required for responsible governance, Internet Computer Protocol tokens (ICP tokens) can be converted to <>. +A <> represents a number of ICP tokens +that cannot be exchanged for a minimum period of time (the lock-up period). +When a person or organization has some number of ICP tokens locked up in a <>, the <> holder has the right to propose and vote on governance issues, and to be paid for voting in proportion to the number of ICP locked up and the length of the lock-up period. +//# end::g-neuron[] + +//# tag::g-node[] [[g-node]] node:: - A physical computer that is a registered member of the {platform} network and running the {IC} replica processes. +A physical or virtual network endpoint that hosts all the hardware, software, and configuration settings required to participate +in the <> network. +//# end::g-node[] + +//# tag::g-principal[] +[[g-principal]] +principal:: +A principal is a byte string that is used to identify an entity, for example a token holder, in the {IC}. +It is the SHA-224 hash of the DER-encoded public key of the entity. +//# end::g-principal[] + +//# tag::g-query[] +[[g-query]] +query:: +A call optimized to allow read-only operations or to perform transient state changes in which the <> state **is not preserved**. ++ + +- Are synchronous and can be made to any <> that holds the <>. +- Do not require consensus to verify the result. +There is an inherent tradeoff between security and performance because the reply from a single <> might be untrustworthy or inaccurate. +//# end::g-query[] + +//# tag::g-replica[] +[[g-replica]] +replica:: +In the context of the {IC}, a replica refers to the {IC} processes (for example, the `+replica+`, `+nodemanager+`, and other lower-level {IC} protocol processes) running on a physical or virtual <> in the network. ++ +Within {IC} protocol documentation, replica is most often used to represent the set of protocol components that are necessary for a <> to participate in a network. ++ +For the {sdk-short-name}, you use the `+dfx start+` and `+dfx stop+` commands to start and stop the `+replica+` processes locally to provide a local network for development. +//# end::g-replica[] +//# tag::g-wallet[] [[g-wallet]] wallet:: - On the {IC}, a wallet is a specialized application that allows you to store and retrieve your digital assets. - The wallet application is implemented as a canister that runs on the {IC}. A wallet enables you to manage your ICP token balances, convert ICP token into cycles, and distribute cycles to your own or other users' canisters as a means for accessing or providing internet services. +On the {IC}, a wallet is a specialized application that allows you to store and retrieve your digital assets. ++ +The default wallet application is implemented as a canister that runs on the {IC}. A wallet enables you to manage your ICP token balances, convert ICP token into cycles, and distribute cycles to your own or other users' canisters as a means for accessing or providing internet services. +//# end::g-wallet[] +//# tag::g-wasm[] [[g-wasm]] WebAssembly:: - https://webassembly.org/[WebAssembly] (`+Wasm+`) is a low-level computer instruction format. - Because WebAssembly defines a portable,open-standard, binary format that abstracts cleanly over most modern computer hardware, it is broadly supported for programs that run on the internet. - Programs written in {proglang} are compiled to WebAssembly code for execution on {IC} replicas. +https://webassembly.org/[WebAssembly] is a low-level computer instruction format. ++ +Because WebAssembly defines a portable,open-standard, binary format that abstracts cleanly over most modern computer hardware, it is broadly supported for programs that run on the internet. ++ +The {sdk-short-name} provides enhanced support for programs written in {proglang} or Rust to run on the {IC}. +However, you can write programs in any language that can be compiled to WebAssembly for deployment on the {IC}. +//# end::g-wasm[] \ No newline at end of file diff --git a/modules/ic-protocol-spec/icp-nav.adoc b/modules/ic-protocol-spec/icp-nav.adoc new file mode 100644 index 000000000..e69de29bb diff --git a/modules/ic-protocol-spec/pages/icp-glossary.adoc b/modules/ic-protocol-spec/pages/icp-glossary.adoc new file mode 100644 index 000000000..ff283ffc1 --- /dev/null +++ b/modules/ic-protocol-spec/pages/icp-glossary.adoc @@ -0,0 +1,374 @@ += Glossary +:sdk-short-name: DFINITY Canister SDK +:stem: latexmath :stem: latexmath +:icons: font + +This section provides definitions for terms used to describe the {IC} and the internal workings of the {IC} protocol in technical documentation and specifications. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-app-canister] + +[[application-state]] +application state:: + Compiled WebAssembly (wasm) module implementing the <> functionality and its dependent modules, together with an instance of each of the modules. + +[[batch]] +batch:: + An ordered set of <> that have been agreed-upon order by a sufficient number of <>, and finalized by <>. + Once assembled into a batch, the messages are available for the <> layer to add to the <>. + +[[bounded-time--eventual-delivery]] +bounded-time / eventual delivery:: + The <> (IC replicas) of a <> form a dedicated <> broadcast network that facilitates the secure “bounded-time/eventual delivery” broadcast of artifacts (such as <>, control messages and their signature shares). + More precisely, up to a certain maximum volume of valid artifacts that are not dropped by any honest <> reaches all honest nodes in bounded time/eventually, despite attacks (under certain network assumptions). + The <> layer builds upon this functionality. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-canister] + +[[canister-pool]] +canister pool:: + The collection of all <> on any given <>. + +[[canister-messages]] +canister messages:: + A message sent from one <> to another. Note that a <> message can be an application-generated <> sent from one <> to another or a system-generated <> sent from one <> to another and that the <> can be on the same or different <>. This type of message is also referred to as a *canister-to-canister* message or an <>. + +[[canister-migration]] +canister migration:: + The system services and components that interact with the replica and NetOS to enable <> to be moved from one <> to another. + CanisterMigration is a sub-component of NetOS (and part of the <>) involved in migrating <> from one <> to another. + +[[canister-state]] +canister state:: + The entire current state of a <>, consisting of the <> and the <>, and the <> code (excluding the Input and OutputQueues). + +[[catch-up-package-CUP]] +catch-up package (CUP):: +Contains all necessary data to bootstrap a <> participant. + +[[certified-non-mutating-query]] +certified non-mutating query:: +A query call that reads data from a <> that has been +cryptographically certified by a quorum of <>. + +[[certified-variables]] +certified variables:: +Global variables that are signed by the hosting <> after each round, such that it can be exposed to users much faster than the rest of the <>. + +[[g-consensus]] +consensus:: +In distributed computing, *consensus* is a fault tolerant mechanism by which a sufficient number of processes in a group can reach agreement about a value or state. ++ +For the <>, *consensus* is a core component of the <> software. The consensus layer selects <> from the peer-to-peer artifact pool and pulls <> from the cross-network streams of other <> and organizes them into a <> with a sequence that sufficiently many <> agree upon before the batch is delivered to the <> layer. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-controller] + +[[Cryptographic-Service-Provider-CSP]] +Cryptographic Service Provider (CSP):: +*Cryptographic Service Provider (CSP)* sub-component that performs all cryptographic operations, such as randomness generation and public and secret key operations. The CSP interface allows one to reference algorithms and secret keys by their identifiers. The secret key values are then picked up from the key store, while the public key values are passed directly to the CSP interface. This component is unaware of the specifics of the https://internetcomputer.org<> platform, such as message types, identities and algorithms mapping, and so on. The CSP contains the stateless implementation of all cryptographic algorithms (together with the low-level group operations) that are used within the https://internetcomputer.org +<>. + +[[CSP]] +CSP:: +See <>. + +[[CUP]] +CUP:: +See <>. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-cycles] + +[[data-center-provider]] +__((Data Center Provider__:: + +[[default-canister]] +__((default canister__:: + +[[DFN-tokens]] +DFN tokens:: +__**Deprecated** terminology for the <> native currency. The native currency was previously referred to as https://internetcomputer.org[Internet Computer] network tokens or as DFN. +The native currency is now referred to as ICP tokens. +__ + +[[distributed-key-generation-DKG]] +__((distributed key generation (DKG)__:: + +[[epoch]] +epoch:: +Represents the number of consecutive <> rounds during which the <> membership stays the same and <> can reach finalization with a very high degree of probability guarantee. + +[[eventual-delivery-bounded-time]] +eventual delivery / bounded-time:: +See <>. + +[[execution-cycle]] +execution cycle:: +An event invoked by the <> scheduler upon receipt of a new InputBlock during which it executes as much of the induction pool as possible + +[[execution-environment]] +execution environment:: +For the <<>>, the <> is a core component of the <> software. The <> provides a runtime environment for executing <> modules. After the <> layer identifies the <> that will handle processing for an <>, the <> processes the <> in the order in which it receives it. + +[[funding-partners-FP]] +__((funding partners (FP)__:: + +[[gas]] +gas:: +**Deprecated** terminology that represents the unit of measurement for resources consumed in the form of processing time, memory an application requires for storage, and network bandwidth. The gas used +to pay for resources consumed by a <> is held in an account on behalf of a user or an application. + +[[genesis-token-canister-GTC]] +genesis token canister (GTC):: +A genesis token <> is a special <> for funding partners and seed-round investors that contains ICP tokens issued at the launch of the Internet Computer public network (the genesis event). + +[[gossip-protocol]] +gossip protocol:: +A *gossip protocol* is a common approach to communication for distributed systems that is analogous to how information spreads from person to person in a social network. With a *gossip protocol*, information spreads from computer to computer in the form of broadcast <> with each computer only disseminating the information to its network neighbors. +For the Internet Computer, gossip is used in the peer-to-peer layer of the <> to advertise the artifacts the <> has received to the neighboring peers it has been assigned. + +[[GTC]] +GTC:: +See <>. + +[[ICA]] +ICA:: +See <>. + +[[ICNS]] +ICNS:: +*Deprecated*. See <> + +[[ICP]] +ICP:: +See <>. + +[[ICPId]] +ICPId:: +*Deprecated*. See <>. + +[[induction-pool]] +induction pool:: +Collection of input queues of all <> on a <>. + +[[ingress-message]] +ingress message:: +A <> sent by an end-user to an <> that is routed through consensus. + +[[ingress-message-history]] +ingress message history:: +Records every processed <> with a boolean flag to indicate whether it was successfully included in the <> or not and, potentially, the response. + +[[input-batch-queue]] +input batch queue:: +Ordered sequence of blocks produced by the <> component + +[[input-pool]] +input pool:: +Collection of <>. + +[[Input-queue]] +Input queue:: +Contains <> to <> <>. Held by the receiving <>. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-intercanister-call] + +[[internet-computer]] +Internet Computer:: +The **Internet Computer** is a decentralized platform that enables a global network of connected computers to provide scalable computing capacity for running application software. + +[[Internet-Computer-Association-ICA]] +Internet Computer Association (ICA):: +The **Internet Computer Association** is a legally-recognized entity (under Swiss law) for member organizations that participate in the development and deployment of the <> as a computing platform. The association includes the https://dfinity.org[DFINITY Foundation], independent data centers, universities, and developer partners that have registered and been accepted as members. + +[[Internet-Computer-nervous-system-ICNS]] +Internet Computer nervous system (ICNS):: +**Deprecated** terminology for the <> governance system. See *network nervous system (NNS)*. + +[[Internet-Compute-Provider-ICP]] +Internet Compute Provider (ICP):: +**Deprecated** terminology for <>. + +[[Internet-Compute-Provider-Identity-ICPId]] +Internet Compute Provider Identity (ICPId):: +**Deprecated** terminology for the identifier associated with each <>. + +[[mainnet]] +mainnet:: +*Deprecated* terminology for the platform management network. See <> and *registry*. + +[[g-message]] +message:: +Data sent from one <> to another, from a user to a <>, or between system components. + +[[message-routing]] +message routing:: +For the <>, <> is a core component of the <> software. The <> layer receives the <> batches from the <> layer, extracts the <> in order, and schedules the <> for execution. ++ +After <> are executed, the <> layer takes any <> produced in the execution cycle from the application output queues and puts those <> into the outgoing streams to be consumed by <> on other <>. + +[[mutating-call]] +mutating call:: +A “write” call that changes the state of the queried <>. + +[[neighboring-peers]] +neighboring peers:: +The <> that exchange gossip with each other based on their network overlay topology. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-nns] + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-neuron] + +[[NID]] +NID:: +See <>. + +[[NNS]] +NNS:: +See <>. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-node] + +[[node-identifier-NID]] +node identifier (NID):: +The unique identifier of a <>. This identifier is a 29-byte selfauthenticating SHA-224 hash of its private key with the byte 0x02 appended as defined in the link:../interface-spec/index{outfilesuffix}[_Interface Specification_]. + +[[node-operator]] +node provider:: +A *node provider* is an entity that provides and operates a <>. The *node provider* is remunerated periodically for providing <> in the form of newly minted ICP tokens. + +[[node-operator-identifier-NOID]] +node operator identifier (NOID):: +The unique identifier of a <>. This identifier is a 29-byte self-authenticating SHA-224 hash of the public key stored on its https://en.wikipedia.org/wiki/Hardware_security_module[HSM] with the byte 0x02 appended as defined in the link:../interface-spec/index{outfilesuffix}[_Interface Specification_]. + +[[NOID]] +NOID:: +See <>. + +node identifier (NID):: + +[[non-mutating-query]] +non-mutating query:: +A “read” operation call that does not change the state of the queried <>. +More commonly, this type of operation is simply referred to as a *query*. + +__((orthogonal persistence__:: + +[[output-pool]] +output pool:: +Collection of output queues of all <> on a <>. + +[[output-queue]] +output queue:: +Contains <> to <> messages. Held by the sending <>. + +[[output stream]] +output-stream:: +A sequence of output <> from the different <> +output queues. + +__((overlay network__:: + +[[P2P]] +P2P:: +See <>. + +[[peer-to-peer-P2P]] +peer-to-peer (P2P):: +In common usage, *peer-to-peer (P2P)* computing or networking is a distributed application architecture that partitions workload across a network of equally-privileged computer <> so that participants can contribute resources such as processing power, disk storage, or network bandwidth to handle application workload. ++ +For the <>, *peer-to-peer* is a core component of the *replica* software. +The *peer-to-peer layer* collects and advertises <> and artifacts from users and from other <> in its <>. ++ +The primary purpose of the peer-to-peer layer is to make the artifact pool consistent across all of the <> in a given <> before sequencing by <>. + +[[pre-processing]] +pre-processing:: +Phase triggered by a new InputBlock during which the <> component puts the <> and <> from the <> streams into the Induction Pool as appropriate, updates the IngressMsgHistory, manages the OutputQueue and creates SignalingMessages as a reaction to XNet <>. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-principal] + +[[post-processing]] +post-processing:: +Once execution is finished, the <> layer produces a new set of output streams from the <>. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-query] + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-replica] + +[[registry]] +registry:: +The *Registry* manages the system meta-data (that will eventually) be maintained on the <>. ++ +The GlobalRegistry is a read-only versioned per value structured data store which support `get(key, version)`. Each call to `get(key, version)` returns the implied struct of the key, where each field is last written at `version` or earlier. ++ +The RegistryManager is a <> replicated by the <> which enforces schema on update. + +[[retransmission-request]] +retransmission request:: +In the <> layer, a peer sends a so-called *retransmission request* to update the other peers about the current status of its artifact pool after a disruption (due to network issues or peer reboot). +The receiving peers use this information to determine which adverts and artifact requests to send. As such, the <> could also be called an artifact pool status <>. + +[[rotating-log]] +rotating log:: +*Deprecated terminology* for where information about user-generated update call is recorded. See <>. + +[[signal-messages]] +signal messages:: +Signal messages acknowledge the receipt of <> sent on behalf of a <> as follows: + +- ERROR: Indicates that a Xnet <> has been rejected. +- ACK: Indicates that a Xnet <> has been processed. + +[[state-change]] +state change:: +A *state change* is the result of any transaction, function call, or operation that changes the information stored for an application. For example, if a function makes an update call that adds two numbers together or removes a name from a list, the result is a change to the application state. + +[[state-manager]] +state manager:: +The *state manager* is responsible for + +* maintaining (multiple versions of) the replicated state the deterministic state machine implemented by <> and the <> operates on, +* converting back and forth between the replicated state and its canonical version (latter can be understood independent of the concrete implementation), +* obtaining certifications of parts of the canonical state, which allow other stakeholders such as other <> and/or users, to verify that some piece of state indeed originates from a valid sub-network, and +* providing capabilities to sync the canonical state with other <> in the same <> so that <> that have fallen behind can catch up. + +[[sub-network]] +__((sub-network / subnet:: + +[[subnet-protocol-replica]] +subnet protocol replica:: +The set of Internet Computer protocol components that are necessary for a <> to participate in a <>. + +[[system-canister]] +system canister:: +A pre-installed <> that performs certain management tasks needed to maintain the <> network. + +[[system-state]] +system state:: +Auxiliary state of a <> that is maintained by the system on behalf of the <>, including DFN balance, its allocations, meta-data. + +[[THID]] +THID:: +See <>. + +[[token-holder-identifier-THID]] +token holder identifier (THID):: +The *token holder identifier* is defined as the SHA-256 hash of the token holder's https://en.bitcoin.it/wiki/BIP_0032#Extended_keys[extended public key]. + +[[TsDemuxTxDemux]] +TsDemuxTxDemux:: +Demultiplexes different types of input messages and routes them to the right destination + +[[uncertified-non-mutating-query]] +uncertified non-mutating query:: +Asks one or multiple <> about uncertified data and takes the <>’s word. + +[[user]] +user:: +Depending on context, any entity that interacts with the <> platform but is not a direct participant +in network operations might be referred to a user. For example, while participants might include <> <>, and <> stakeholders, users might include end users, third party developers, and server operators. + +[[valid-set-rule]] +valid set rule:: +The set of checks that every <> and <> from a finalized batch must pass before it can be added to the appropriate application input queue in the induction pool. + +include::developers-guide:page$glossary.adoc[leveloffset=2,tag=g-wasm] \ No newline at end of file