Working with contexts

A context is a running instance of an application with its own state, belonging to a group. This guide covers the context lifecycle and calling into an app. Every method returns a plain Python value (usually a dict or list).

Creating a context

A context is created inside a group, so you need a group_id (from a namespace or group — see namespaces and groups) and an installed application (see applications and blobs):

result = client.create_context(
    application_id="<application-id>",
    group_id="<group-id>",
    params='{"init": true}',   # optional: initialization params (a string)
    service_name=None,          # optional
)

params and service_name are optional. params is passed through as the application’s initialization payload.

To create a fresh identity for use in a context:

identity = client.generate_context_identity()

Inspecting contexts

client.list_contexts()                       # all contexts on the node
client.get_context("<context-id>")           # one context's metadata
client.get_context_storage("<context-id>")   # storage/state info
client.get_context_identities("<context-id>")   # identities in the context
client.get_context_client_keys("<context-id>")  # client keys

Context IDs are validated: an invalid ID raises ValueError.

Joining and leaving

client.join_context("<context-id>")   # join via group membership
client.leave_context("<context-id>")  # local leave — stops sync, reversible

leave_context is a local operation: it stops syncing the context on this node and disarms auto-follow, without publishing anything. Calling join_context again reverses it.

To remove a context entirely:

client.delete_context("<context-id>")                       # requester optional
client.delete_context("<context-id>", requester="<public-key>")

Syncing state

client.sync_context("<context-id>")   # sync one context
client.sync_all_contexts()            # sync every context on the node

For a context that can no longer replay its history (for example a missing bytecode blob), resync_context adopts a peer’s full-state snapshot. It is destructive — pass force=True when the context still holds local heads:

client.resync_context("<context-id>", force=True)

Executing application functions

Call a method on the app running in a context over JSON-RPC. Arguments are a JSON string:

result = client.execute_function(
    context_id="<context-id>",
    method="set",
    args='{"key": "greeting", "value": "hello"}',
)

The trailing executor_public_key argument is accepted for backward compatibility but ignored — the node auto-resolves the context’s owned identity. Invalid JSON in args raises ValueError.

To point a context at a different application version:

client.update_context_application(
    context_id="<context-id>",
    application_id="<new-application-id>",
    executor_public_key="<public-key>",
)

Context aliases

Give a context (or a context identity) a human-friendly alias:

client.create_context_alias("my-context", "<context-id>")
client.create_context_identity_alias("<context-id>", "alice", "<public-key>")

client.lookup_context_alias("my-context")     # resolve without side effects
client.resolve_context_alias("my-context")    # resolve to the value
client.list_context_aliases()                 # all context aliases
client.delete_context_alias("my-context")

The API reference lists the full alias surface, including the identity- and application-scoped variants. There is also a backward-compatible create_alias_generic(alias, value, scope=None) helper that treats value as a context id — prefer the typed methods above for new code.

Next steps

Applications and blobsInstall applications and move blob data.

Namespaces and groupsCreate the group a context lives in.