SCION endhost software development kit (SDK)

Supercharge your applications with SCION's path-aware networking capabilities!

The SCION endhost SDK provides the tools and libraries necessary to build applications that can leverage the full potential of the SCION Internet architecture. It enables developers to create path-aware, secure, and reliable applications that can intelligently select their network paths, providing enhanced control over their network traffic.

This SDK is developed and maintained by Anapaya, a leading SCION technology company. We thank our colleagues at Mysten Labs for publishing scion-rs upon which parts of this SDK are based.

SCION is an inter-domain networking architecture — think of it as an alternative to today's BGP-routed Internet — with one property that matters most to application developers: the application, not the network, chooses the path its packets take.

On the SCION network you can:

• See every path to a destination and their properties (which ISDs and ASes they cross, MTU, latency hints) instead of being handed one opaque route.
• Pick a path per packet — steer traffic away from a provider, prefer a low-latency route, or spread load across several paths — from application code.
• Fail over instantly when a path breaks, because you already hold the alternatives.
• Trust the source, because SCION paths are cryptographically authenticated.

The main entry point for using the SCION endhost SDK is the scion-stack crate. It provides the ScionStack type - a stateful object that is the conceptual equivalent of the UDP/TCP/IP networking stack found in typical operating systems.

To use the SCION endhost SDK in your Rust project, add the scion-stack crate as a dependency in your Cargo.toml:

cargo add scion-stack

The following example demonstrates how to create a ScionStack and bind a path-aware UDP socket. This type of socket automatically manages path selection, simplifying the process of sending and receiving data over the SCION network.

use scion_stack::stack::{ScionStack, ScionStackBuilder};
use sciparse::address::ip_socket_addr::ScionSocketIpAddr;
use url::Url;

async fn socket_example() -> Result<(), Box<dyn std::error::Error>> {
    // Point the stack at your local SCION endhost API.
    let endhost_api: Url = "http://127.0.0.1:1234".parse()?;
    let builder = ScionStackBuilder::new().with_endhost_api(endhost_api);

    let scion_stack = builder.build().await?;
    let socket = scion_stack.bind(None).await?;

    let destination: ScionSocketIpAddr = "1-ff00:0:111,[192.168.1.1]:8080".parse()?;

    socket.send_to(b"hello", destination).await?;
    let mut buffer = [0u8; 1024];
    let (len, src) = socket.recv_from(&mut buffer).await?;
    println!("Received: {:?} from {:?}", &buffer[..len], src);

    Ok(())
}

The full developer guide is published at https://learn.anapaya.net/docs/academy/scion-sdk. That site tracks the latest released version of the SDK.

To preview the documentation for the current HEAD of this repository instead, use the standalone preview app in docs/preview/:

cd docs/preview
pnpm install
pnpm start          # http://localhost:3000 (live reload)

The SCION endhost SDK lives under crates/, organized into building-block libraries (crates/libs/) and API/RPC binding families (crates/apis/), with the main components at the top level. The most relevant crates are:

• scion-stack: The main entry point for creating SCION sockets. It provides the ScionStack and related components for building SCION applications.
• pocketscion: A SCION simulator for local development and testing.
• snap: A client implementation for the SNAP (SCION Network Access Point) transport underlay.
• sciparse: Contains the definitions for SCION data plane and control plane entities, such as packet formats and control plane messages.

Language bindings live outside crates/:

• bindings/android/: Packages the SCION HTTP/3 client into an Android library (AAR), cross-compiling scion-http3-ffi for arm64-v8a and x86_64.
• bindings/apple/: Packages the SCION HTTP/3 client into a Swift package for iOS and macOS, cross-compiling scion-http3-ffi into an XCFramework with a hand-written Swift facade on top.

We welcome contributions from the community! If you'd like to help improve the SCION endhost SDK, here's how you can get started:

• Bug reports and feature requests: If you encounter a bug or have an idea for a new feature, please open an issue using the appropriate issue template (bug report or feature request, once they are available).
• Pull requests: We encourage you to contribute code! To submit a pull request, please follow this workflow:
  1. Fork the repository.
  2. Create a new branch for your changes.
  3. Make your changes and commit them with a clear and descriptive message.
  4. Submit a pull request to the main branch of the original repository.
  5. Address any feedback or requested changes from the maintainers.
  6. Once approved, your changes will be first synced to our internal repository, merged, and then published to the public repository. We will make sure to properly attribute your contribution in the commit history.

For larger features or significant changes, we recommend opening an issue first to discuss your plans with the maintainers. This helps ensure that your work aligns with the project's goals and avoids duplication of effort.

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.

For any questions or inquiries, please contact us at [email protected].