Introduction and key concepts

You don’t need to know much about the inner workings of the Internet Computer platform to write programs that run successfully on it. However, learning a few key concepts will help you get the most out of the unique features that the Internet Computer provides.

Knowing a little about the design and architecture of the Internet Computer platform can make it easier for you to realize the benefits that align with your goals and inform the types of applications you develop. If you want to get right to developing code, though, you can skip this introductory material—key concepts and terminology—and look them up later when you need them either in this section or in the glossary provided at the end of this guide.

What is the Internet Computer?

The Internet Computer is a computing infrastructure that enables developers, organizations, and entrepreneurs to build and deploy secure, autonomous, and tamper-proof software programs. Unlike most cloud-based or distributed architectures, however, the Internet Computer provides an open platform where software and services run directly on the internet itself rather than on a proprietary infrastructure or a specific hosting service.

As an application developer, you might find it useful to think of the Internet Computer as providing the following key infrastructure elements:

  • An open communication protocol that enables general-purpose computations to run transparently directly on the internet

  • A network that runs the protocol to provide computing capacity—for example, the hardware, CPU, and memory required to run programs—through independent data centers.

  • A globally-accessible and scalable platform for running software applications.

Open infrastructure platform

The Internet Computer is not physical hardware that exists in any physical location. Instead, the Internet Computer combines computing resources provided by independent data centers around the world to give users and organizations secure access to applications and transaction processing services.

If you think of the Internet Computer as an infrastructure platform, it is similar to a public cloud provider, like Amazon Web Services (AWS), Google Cloud Platform (GCP), or Microsoft Azure, or to a private cloud managed internally by a private organization.

Unlike a public or private cloud, however, the Internet Computer platform is not owned and operated by a single private company. Instead, platform updates and operations are managed through a decentralized governance system defined in the protocol. Its architecture enables multiple computers to operate like one, very powerful, virtual machine.

The computers that make up the virtual machine are organized into sub-networks of data centers around the globe. The distributed architecture enables secure communication without firewalls or technologies that are vulnerable to attack. Independent data centers receive remuneration for contributing computing capacity and hosting services to support applications running on the Internet Computer platform.

Building the next generation of software and services

The Internet Computer protocol reduces platform-based risks and paves the way for innovation by re-imagining how software is built, deployed, and accessed.

For example, with the Internet Computer, developers can focus on writing code without environment-related distractions such as:

  • physical or virtual network configuration requirements

  • load balancing services

  • firewalls, network topology, or port management

  • database configuration and maintenance

  • storage volumes and devices

By enabling developers to focus on building applications and delivering value, the Internet Computer helps simplify the development process, reduce time to market, and foster innovation.

For end-users, the Internet Computer provides a secure environment for accessing applications with fewer risks. Because of the inherent security of the blockchain, programs running on the Internet Computer cannot be hijacked by malicious code, which also reduces the total cost of ownership for both application end-users or organizations.

In addition, because software services can be "autonomous" and public, developers can write services that communicate with each other and share functions in ways that increase productivity and efficiency while leaving room to innovate and improve projects with confidence.

The Internet Computer also enables developers to use cryptographically-secure identities to enforce access controls, reducing the need to rely on user names and passwords or external identity management plug-ins.

Basic architecture

Internet Computer sub-networks provide physical hardware and resources—like CPU and memory—for performing software operations. Each sub-network consists of some number of individual machines—connected peer computers called nodes—that run the software components of the Internet Computer protocol.

The Internet Computer software components that run on each node are called a replica because they replicate state and computation across all of the nodes in a sub-network.

The core components of a replica are organized into the following logical layers:

  • A peer-to-peer (P2P) networking layer that collects and advertises messages from users, from other nodes in its sub-network, and from other sub-networks. Messages received by the peer-to-peer layer are replicated to all of the nodes in the sub-network to ensure the security, reliability, and resiliency of the platform.

  • A consensus layer that selects and sequences messages received from users and from different subnets to create input blocks that can be notarized and finalized before being delivered to the message routing layer.

  • A message routing layer that routes user- and system-generated messages between subnets, manages the input and output queues for applications, and schedules messages for execution.

  • An execution environment that calculates the deterministic computation involved in executing a program and processes the messages it receives from the message routing layer.

The following diagram provides a simplified overview of the Internet Computer protocol components deployed as a local replica in a development environment.

Internet Computer components in a developer’s environment

As a developer, it isn’t necessary to know the details about how your applications and user interactions with your applications are routed through the Internet Computer architecture or replicated on the network. However, a general understanding of the key components can be useful because the development environment includes the replica components to provide a local test network for deployment and a realistic sense of the workflow for a production deployment.

Writing, deploying, and running software

One of the most important principles to keep in mind is that the Internet Computer is primarily a distributed and decentralized platform for running software.

When you write source code for an application that runs on the Internet Computer, you compile the source code into a WebAssembly module. When you deploy the WebAssembly module that contains your program on an Internet Computer replica, the program is executed inside of a conceptual computational unit called a software canister.

Once deployed, end-users can interact with the software canister by accessing the entry point functions you have defined for that canister through a front-end client such as a browser.

Canisters include both program and state

A software canister is similar to a container in that both are deployed as a software unit that contains compiled code and dependencies for an application or service.

Containerization allows for applications to be decoupled from the environment, allowing for easy and reliable deployment. The canister differs from a container, however, in that it also stores information about the current software state with a record of preceding events and user interactions.

While a containerized application might include information about the state of the environment in which the application runs, a software canister is able to persist a record of state changes that resulted from an application’s functions being used.

This concept of a canister consisting of both program and state is an important one because when a canister function is invoked by sending a message to one of its entry points, there are only two types of calls: non-committing query calls and committing update calls.

Type Key points to remember

Query calls

Allow the user to query the current state of a canister or call a function that operates on the canister’s state without changing it.

  • Are synchronous and answered immediately.

  • Can be made to any node that holds the canister and do not require consensus to verify the result. There is an inherent tradeoff between security and performance because the reply from a single node might be untrustworthy or inaccurate.

  • Do not allow changes to the state of the canister to be persisted. Essentially, programs use query calls to perform read-only operations.

  • Do not allow the called canister to invoke functions exposed by other canisters as inter-canister calls. (Note that this restriction is temporary and that canisters will be able to invoke functions exposed by other canisters when processing query calls in the future.)

Update calls

Allow the user to change the state of the canister and have changes persisted.

  • Are answered asynchronously.

  • Must pass through consensus to return the result. Because consensus is required, changing the state of a canister can take time. Therefore, update calls use the actor-based programming model (with state isolation) to allow concurrent and asynchronous processing. There is an inherent tradeoff between security and performance because two-thirds of the replicas in a subnet must agree on the result.

  • The called canister can invoke functions exposed by other canisters

As a developer, it is important to recognize this relationship between the calls that query the canister and the calls that change the canister state. In particular, you should keep in mind the inherent tradeoff between security and performance.

How to develop applications for the Internet Computer

For programmers and software developers, the Internet Computer platform provides unique capabilities and opportunities within a framework that simplifies how you can design, build, and deploy applications. A key part of this framework is a new, general purpose programming language, Motoko. Motoko is a programming language that has been specifically designed to take full advantage of the unique features that the Internet Computer provides, including:

  • The ability to define programs directly using actor objects and classes.

  • The use of async and await syntax to enable programming asynchronous messaging as if it was synchronous processing.

  • Automatic support for message serialization and deserialization.

  • The ability to leverage orthogonal persistence using data structures without external databases or storage volumes.

As a modern, high-level programming language, Motoko provides some key features of its own, including:

  • Support for big integer operations and overflow protection.

  • A sound type system that statically checks each program to ensure it can execute without type errors on all possible inputs.

  • Support for function abstractions, user-defined type definitions, and user-defined actors.

For more detailed information about the Motoko programming language itself, including syntactical conventions and supported features, see the Motoko Programming Language Guide.

The following diagram provides a simplified drill-down view of the development environment as part of the Internet Computer ecosystem.

Your development environment as part of the Internet Computer ecosystem

Canisters, actors, and the code you produce

One of the most important principles to keep in mind when preparing to write programs using the Motoko programming language is that Motoko uses an actor-based programming model.

An actor is a special kind of object that processes messages in an isolated state, enabling messages to be handled remotely and asynchronously. Many key features of the Internet Computer platform depend on this type of secure and efficient asynchronous message handling.

In general, each software canister includes the compiled code for one actor object. Each canister also includes some additional information such as interface descriptions or front-end assets. You can create projects that include multiple canisters, but each canister can only include one actor.

Why your code is compiled into WebAssembly

When you compile Motoko code, the result is a WebAssembly module. WebAssembly is a low-level computer instruction format that is portable and abstracts program execution cleanly over most modern computer hardware. It is broadly supported for programs that run on the internet and a natural fit for deploying applications that are intended to run on the Internet Computer platform.

With Motoko, developers can compile to portable WebAssembly while still delivering secure applications using a simple and high-level language.

The Motoko language offers many of the features that are common to other higher-level modern languages—like type safety and pattern-matching. In addition, Motoko provides built-in support for defining messaging services using actors in a way that is especially well-suited to the Internet Computer platform and is easy to learn whether you are a new or experienced programmer.

This guide provides an introduction to the basic features of the Motoko programming language in the context of writing programs using the SDK. For more detailed information about the Motoko programming language itself, see the Motoko Programming Language Guide.

Identities and authentication

One of the main differences between a user-initiated canister operation and a canister-to-canister operation is that canisters have an explicitly registered identity on the [IC].

There is no central registry for user principals. Instead, user identifiers are associated specifically with the canisters each user accesses through one or more public-private key pairs. The user’s private key is used to sign messages, which are sent along with their public key to a canister. The [IC] authenticates the user and passes the principal to the canister for the authorization of their operation.

At a high level, first-time users generate an unsigned key pair and derive their principal identifier from the public key during their first interaction with the Internet Computer. Returning users are authenticated using the private key (or keys) that have been stored securely by the user agent. Users with access to multiple canisters can manage the keys and devices used for authentication associated with each canister.

A single user can have multiple public-private key pairs for accessing canisters from different devices—such as browsers running on different computers, mobile phones, or tablets—but these derived keys all map to a primary identifier.

Canisters and resource usage

In general, all canisters consume resources in the form of CPU cycles for execution, bandwidth for routing messages, and memory for persisted data. Canisters maintain an account balance to pay for the cost of communication, computation, and storage their applications consume. The cost of computation is referred to as cycles.

Cycles reflects the real costs of operations including resources such physical hardware, rack space, energy,storage devices, and bandwidth. In simple terms, a unit of cycles represents the cost of executing a single WebAssembly instruction.

  • Programs must be able to pay for complete execution (all or nothing), but the cost associated with a unit of cycles will make efficient programs cost-effective.

  • By setting limits on how many cycles a canister can consume, the platform can prevent malicious code from draining resources

The relative stability of operational costs makes it easier to predict the cycles required to process, for example, a million messages.

When you deploy canisters locally or to an Internet Computer test network, there’s no cost associated with program execution. However, it is possible that in calculating the operations to be performed, executing a program might result in an “out of cycles” exception because the operations would exceed a predefined threshold. If you see this exception in testing, you can temporarily configure a higher cycles limit by setting a command-line option.