Skip to main content

Python Client Reference

Nillion Client Python module.

exception py_nillion_client.AuthenticationError​

Error related to authentication: invalid password, public key, or other internal errors

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.ClusterDescriptor​

The ClusterDescriptor contains attributes that describe the cluster configuration. It includes information about:

  1. Cluster id;
  2. Security parameters (statistical security and security threshold);
  3. Parties (nodes) in the cluster;
  4. Preprocessing configuration.

This object is returned when invoking NillionClient cluster_information method.

Example​

cinfo = await client.cluster_information(args.cluster_id)

id​

The Cluster identifier.

  • Return type: A string containing the Nillion Cluster identifier.

Example​

cinfo = await client.cluster_information(args.cluster_id)
print("Cluster id:", cinfo.id)
>>> Cluster id: 147f8d45-2126-4a54-9a64-8141ee55f51a

kappa​

The statistical security parameter kappa for this cluster.

  • Return type: The value of the statistical security parameter kappa used in this cluster.

Example​

cinfo = await client.cluster_information(args.cluster_id)
print("Statistical sec parameter kappa:", cinfo.kappa)
>>> Statistical sec parameter kappa: 40

parties​

Cluster’s parties ids.

  • Return type: A list of strings containing the party identifiers in the cluster.

Example​

cinfo = await client.cluster_information(args.cluster_id)
print("Cluster parties' ids:", cinfo.parties)
>>> Parties: {'12D3KooWJtRXjmV1HctQgvLUcrdxJ7cXwCHiL6PCheikN2rTJ2ZH',
              '12D3KooWHSveXS4DdXpCQyDDsp9D1x7fiTRnm1fsH9yJRpR6y4FM',
              '12D3KooWLV6HzUXpt6Tt5HUM5Fo3mpjvwsv9n4ADkJ962ArAZCvX'}

polynomial_degree​

The polynomial degree used by this cluster. The polynomial degree is directly related with the security threshold of the Nillion network.

  • Returns:
    • An integer corresponding to the degree of the polynomial used
    • in the cluster for linear secret sharing.

Example​

cinfo = await client.cluster_information(args.cluster_id)
print("Polynomial degree:", cinfo.polynomial_degree)
>>> Polynomial degree: 1

preprocessing​

The preprocessing configuration. It includes the batch size of preprocessing material:

  1. Alpha;
  2. Lambda;
  3. Comparison;
  4. Division;
  5. Modulo;
  6. Public output equality.

Example​

cinfo = await client.cluster_information(args.cluster_id)
cluster_preprocessing_info = cinfo.preprocessing

prime​

The prime number used in this cluster.

  • Return type: The identifier of the prime used in the cluster.

Example​

cinfo = await client.cluster_information(args.cluster_id)
print("Prime type:", cinfo.prime)
>>> Prime: U256SafePrime

exception py_nillion_client.ComputeError​

Error related to the computation itself: initialization, scheduling, or other internal errors

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.ComputeFinishedEvent​

The ComputeFinishedEvent class is returned by an async computation when the computation has just finished.

This class has no public constructor and is received from method NillionClient.next_compute_event().

result​

The computation’s result, as a FinalResult class.

Use the FinalResult.value() method to obtain the wrapped value.

Example​

uuid = await client.compute(
    args.cluster_id,
    bindings,
    [store_id],
    args.compute_secrets,
    args.compute_public_variables,
)

while True:
    event = await client.next_compute_event()
    if isinstance(event, nillion.ComputeScheduledEvent):
        pass
    if isinstance(event, nillion.ComputeFinishedEvent) and event.uuid == uuid:
        print(
            f"Received computation result for {event.uuid}, result = {event.result}"
        )
        print(
            f"Received computation result value for {event.uuid}, value = {event.result.value}"
        )
        break

uuid​

The computation’s UUID.

  • Returns: Uuid
  • Return type: str

Example​

uuid = await client.compute(
    args.cluster_id,
    bindings,
    [store_id],
    args.compute_secrets,
    args.compute_public_variables,
)

while True:
    event = await client.next_compute_event()
    if isinstance(event, nillion.ComputeScheduledEvent):
        pass
    if isinstance(event, nillion.ComputeFinishedEvent) and event.uuid == uuid:
        print(
            f"Result for computation with UUID {event.uuid} is ready!"
        )
        break

class py_nillion_client.ComputeScheduledEvent​

The ComputeScheduledEvent class is returned by an async computation when the computation is not finished yet.

This class has no public constructor and is received from method NillionClient.next_compute_event().

uuid​

The computation’s UUID. This outputs the same UUID provided by the NillionClient.compute() method.

  • Returns: Computation UUID.
  • Return type: str

Example​

uuid = await client.compute(
    args.cluster_id,
    bindings,
    [store_id],
    args.compute_secrets,
    args.compute_public_variables,
)

event = await client.next_compute_event()
if isinstance(event, nillion.ComputeScheduledEvent):
    computation_uuid = event.uuid

class py_nillion_client.ConnectionMode​

This is a ConnectionMode class. It designates the connection mode to use in a client constructor. We support three different modes:

  1. Dialer (dialer());
  2. Direct (direct());
  3. Relay (relay()).

dialer()​

Specifies the client should connect in dialer mode. In this mode the client only expects to dial nodes and does not expect any incoming connection.

Example​

connection_mode = ConnectionMode.dialer()

direct()​

Specifies a socket address structure for a listening client connection.

This mode is suited for clients that are backend services.

  • Parameters: str – Socket address structure.
  • Return type: ConnectionMode

Example​

connection_mode = ConnectionMode.direct('0.0.0.0:11337')

relay()​

Specifies the client connects to the Nillion Network in relay mode. So, if others want to contact the client, they have to do so through a relay node that the client is connected to (all nodes in the network are relay nodes).

This mode is suited for clients that cannot open a port like phones behind a CGNAT, desktop apps behind a NAT or Firewall, and others.

Example​

connection_mode = ConnectionMode.relay()

exception py_nillion_client.DealerError​

Error related to the dealers: initialization, scheduling, unexpected errors

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.FinalResult​

This is a FinalResult class that is returned from a finished computation.

This class has no public constructor and is received from method ComputeFinishedEvent.result().

value​

The result’s value of a computation.

  • Returns: Result value from a computation.
  • Return type: Dict

Example​

uuid = await client.compute(
    args.cluster_id,
    bindings,
    [store_id],
    args.compute_secrets,
    args.compute_public_variables,
)

while True:
    event = await client.next_compute_event()
    if isinstance(event, nillion.ComputeScheduledEvent):
        pass
    if isinstance(event, nillion.ComputeFinishedEvent) and event.uuid == uuid:
        print(
            f"Received computation result value for {event.uuid}, value = {event.result.value}"
        )
        break

class py_nillion_client.NillionClient(node_key, bootnodes, connection_mode, user_key, payments_config, whitelist=None)​

The NillionClient class serves as the primary tool for connecting to the Nillion network and facilitating various operations. It allows users to interact with the Nillion network efficiently, including for the following actions:

  1. Store Nada programs (store_program());
  2. Store secrets (store_secrets());
  3. Update secrets (update_secrets());
  4. Retrieve secrets (retrieve_secret());
  5. Delete secrets (delete_secrets());
  6. Compute a Nada program over some secrets (compute());
  7. Receive compute results (next_compute_event()).

An instance of NillionClient can embody either a dealer node, responsible for providing inputs, or a result node, tasked with receiving computation outputs. Under the hood, this spawns a set of actors and acts as a node in the network that has both dealer and result node capabilities.

Note: multiple instances can be employed concurrently if required; however, it is imperative that each instance possesses a distinct NodeKey when utilized within the same interpreter.

  • Parameters:
    • node_key (NodeKey) – A private key to use for the Client node.
    • bootnodes (list of str) – A list of nodes belonging to the network (other may be discovered later).
    • connection_mode (ConnectionMode) – How to connect to the network, either directly (indicating a listen address), through a relay server or as a dialer client.
    • user_key (UserKey) – User credentials to use.
    • payments_config (PaymentsConfig) – The payments configuration to use.
    • whitelist (list of str , optional) – A list of peer ids to connect to/from.
  • Returns: Instance of the NillionClient and an event receiver channel used to retrieve computation results.
  • Return type: NillionClient

Example​

For further information about the structure of the objects used by the constructor, we refer to the quickstart guide .

import py_nillion_client as nillion

node_key = nillion.NodeKey.from_file(os.getenv("NILLION_NODEKEY_PATH"))
bootnodes = [os.getenv("NILLION_BOOTNODE_MULTIADDRESS")]
connection_mode = nillion.ConnectionMode.dial()
user_key = nillion.UserKey.from_file(os.getenv("NILLION_USERKEY_PATH"))
rpc_endpoint = os.getenv("NILLION_BLOCKCHAIN_RPC_ENDPOINT")
wallet_private_key = os.getenv("NILLION_WALLET_PRIVATE_KEY")
chain_id = int(os.getenv("NILLION_CHAIN_ID"))
payments_address = os.getenv("NILLION_PAYMENTS_SC_ADDRESS")
blinding_factor_manager_address = os.getenv("NILLION_BLINDING_FACTORS_MANAGER_SC_ADDRESS")
payments_config = nillion.PaymentsConfig(
          rpc_endpoint,
          wallet_private_key,
          chain_id,
          payments_address,
          blinding_factor_manager_address,
      )

client = nillion.NillionClient(
      node_key,
      bootnodes,
      nillion.ConnectionMode.relay(),
      user_key,
      payments_config
  )

cluster_information(cluster_id)​

Get information about a cluster by returning an instance of the ClusterDescriptor class. We can access various information about the cluster through its methods.

  • Parameters: cluster_id (str) – UUID of the targeted preprocessing cluster.
  • Return type: An instance of ClusterDescriptor populated with the cluster information.

Example​

cluster_id = os.getenv("NILLION_CLUSTER_ID")
await client.cluster_information(args.cluster_id)

compute(cluster_id, bindings, store_ids, secrets, public_variables)​

Requests a compute action in the Nillion Network for a specific Nada program under a set of secrets.

Note: This method does not directly output the result of the Nada program. Instead, it returns a computation UUID. To obtain the result, you’ll need to fetch it separately. The UUID, in conjunction with the event provided by the corresponding NillionClient instance channel, allows you to retrieve the computation results. Please refer to the e xample below for clarification.

  • Parameters:
    • cluster_id (str) – UUID of the targeted preprocessing cluster
    • bindings (ProgramBindings) – The prepared program specification and secret bindings
    • secrets (Secrets) – Additional secrets to use for the computation
    • store_ids (list of str) – List of the store IDs (uuids) of the secrets to use for the computation
    • public_variables (PublicVariables) – Public variables to use for the computation
  • Returns: A computation UUID.
  • Return type: str

Example​

import py_nillion_client as nillion

bindings = nillion.ProgramBindings(args.program_id)
bindings.add_input_party("Dealer", client.party_id)
store_id = await client.store_secrets(
    args.cluster_id, bindings, args.store_secrets, None
)

bindings = nillion.ProgramBindings(args.program_id)
bindings.add_input_party("Dealer", client.party_id)
bindings.add_output_party("Result", client.party_id)

uuid = await client.compute(
    args.cluster_id,
    bindings,
    [store_id],
    args.compute_secrets,
    args.compute_public_variables,
)

while True:
    event = await client.next_compute_event()
    if isinstance(event, nillion.ComputeScheduledEvent):
        pass
    if isinstance(event, nillion.ComputeFinishedEvent) and event.uuid == uuid:
        print(
            f"Received computation result for {event.uuid}, result = {event.result}"
        )
        print(
            f"Received computation result value for {event.uuid}, value = {event.result.value}"
        )
        break

delete_secrets(cluster_id, store_id)​

Delete existing secrets.

  • Parameters:
    • cluster_id (str) – UUID of the targeted preprocessing cluster
    • store_id (str) – The secret’s store identifier to be deleted (returned when calling store_secrets())
  • Return type: None

Example​

await client.delete_secrets(cluster_id, store_id)

next_compute_event()​

Returns the state of the computation in the Nillion Network.

If the event is from an ongoing computation, it only includes the corresponding UUID from the compute() process. Once the computation is complete, the event includes both the UUID and the computation result (FinalResult).

  • Returns: Either event type will pull the next compute event from the internal result channel which can be inspected to determine if compute operation has completed
  • Return type: ComputeScheduledEvent | ComputeFinishedEvent

Example​

uuid = await client.compute(
    args.cluster_id,
    bindings,
    [store_id],
    args.compute_secrets,
    args.compute_public_variables,
)

while True:
    event = await client.next_compute_event()
    if isinstance(event, nillion.ComputeScheduledEvent):
        print(
            f"Waiting for computation with UUID={event.uuid} to finish."
        )
    if isinstance(event, nillion.ComputeFinishedEvent) and event.uuid == uuid:
        print(
            f"Received computation result for {event.uuid}, result = {event.result}"
        )
        print(
            f"Received computation result value for {event.uuid}, value = {event.result.value}"
        )
        break

party_id​

Returns the SDK client’s instance party ID, which can be used by the client to create program bindings (ProgramBindings, check examples).

Effectively, the party ID is equivalent to the the Peer ID used within libp2p for inter-node communication. It is a hash generated from the public key of the node’s key-pair (NodeKey). Not to be confused with the user_id which is generated from the public key of the user’s key-pair (UserKey).

Read more about party ID and peer ID.

  • Returns: UUID of libp2p party identifier.
  • Return type: str

Example​

print("Party ID:", client.party_id)

retrieve_secret(cluster_id, store_id, secret_id)​

Retrieve a secret stored in the Nillion Network.

To retrieve the value of the secret, you need to use the value attribute on the second element of the output tuple. Check the example below to read the value of a secret integer.

  • Parameters:
    • cluster_id (str) – UUID of the targeted preprocessing cluster.
    • store_id (str) – The secret’s store ID (returned when calling store_secrets()).
    • secret_id (str) – The secret’s ID.
  • Returns: The secret ID as a UUID as well as the secret itself.
  • Return type: tuple

Example​

secret_name = "fortytwo"
result = await client.retrieve_secret(cluster_id, args.store_id, secret_name)
print("Secret ID: ", result[0])
print("Secret Value: ", result[1])
>>> Secret ID: 2424a65c-d20c-4635-b864-06c064188dd4
>>> Secret Value: 42

store_program(cluster_id, program_name, program_mir_path)​

Store programs in the Nillion Network.

The program_id used by store_secrets() and compute() can be built as follows:

client.user_id + "/" + program_name

where client is a NillionClient instantiation and program_name is the name of the program.

  • Parameters:
    • cluster. ( * cluster_id - UUID of the targeted preprocessing) –
    • store. ( * program_name - Name of the program to) –
    • stored. ( * program_mir_path - Path to the MIR program being) –
  • Returns: The action identifier associated with the action of storing a program
  • Return type: str

Example​

program_name = "prog"
program_mir_path = "programs-compiled/prog.nada.bin"

# Store program in the Network
print(f"Storing program in the network: {program_name}")
action_id = await client.store_program(
    args.cluster_id, program_name, program_mir_path
)
print("action_id is: ", action_id)
program_id = client.user_id + "/" + program_name
print("program_id is: ", program_id)

store_secrets(cluster_id, bindings, secrets, permissions)​

Store secrets in the Nillion Network.

  • Parameters:
    • cluster_id (str) – UUID of the targeted preprocessing cluster
    • bindings (ProgramBindings , optional) – bindings between network parties and the parties are defined by the program
    • secrets (Secrets) – The secrets to store; this is a hash map indexed by secret IDs
    • permissions (Permissions , optional) – permissions to be set. By default the user has update and retrieve permissions on the secret as well as compute permissions for the program bound, should there be a program bound.
  • Returns: A store identifier that can be used to retrieve the secret.
  • Return type: str
  • Raises: TypeError – When using bindings, the input party name provided (e.g. “InputPartyName”) must match the input party name in the Nada program. Othersiwe, we get a TypeError.

Example​

Here are some examples of how to use this function. Note that to give permissions we use the User ID and to bind a secret to a program we use the Party ID.

###########################
# Example 1 - Simple      #
###########################
# Notice that both bindings and permissions are set to None.
# Bindings need to be set to use secrets in programs
# Permissions need to be set to allow users other than the secret creator to use the secret
secrets = nillion.Secrets({"fortytwo": nillion.SecretInteger(42)})
store_id = await client.store_secrets(
    cluster_id, None, secrets, None
)

###########################
# Example 2 - Permissions #
###########################
permissions = nillion.Permissions.default_for_user(client.user_id)
permissions.add_retrieve_permissions(set([args.retriever_user_id]))
secrets = nillion.Secrets({"fortytwo": nillion.SecretInteger(42)})
store_id = await client.store_secrets(
    cluster_id, None, secrets, permissions
)
###########################
# Example 3 - Bindings    #
###########################
# Bind to the corresponding party in the program. In this example,
# we are just binding the client but we can bind any other user
# through its Party ID.
bindings = nillion.ProgramBindings(program_id)
# Important note: the name "InputPartyName" must match the input
# party name in the Nada program. Otherwise, the `store_secrets` action
# is not completed and it raises a TypeError.
bindings.add_input_party("InputPartyName", client.party_id)
secrets = nillion.Secrets({"fortytwo": nillion.SecretInteger(42)})
store_id = await client.store_secrets(
    cluster_id, bindings, secrets, None
)

update_permissions(cluster_id, store_id, permissions)​

Update permissions for already stored secret in the Nillion Network.

  • Parameters:
    • cluster_id (str) – UUID of the targeted preprocessing cluster
    • store_id (str) – The secret’s store ID (returned when calling store_secrets())
    • permissions (Permissions , optional) – permissions to be set.
  • Returns: The unique identifier of this update operation ID that can be used to help troubleshoot issues with this operation.
  • Return type: str

Example​

# Store
secrets = nillion.Secrets({"fortytwo": nillion.SecretInteger(42)})
store_id = await client.store_secrets(
  cluster_id, None, secrets, None
)
# Update permissions
permissions = nillion.Permissions.default_for_user(client.user_id)
permissions.add_retrieve_permissions(set([args.retriever_user_id]))
updated_store_id = await client.update_permissions(args.cluster_id, store_id, permissions)

print("Stored secret id: ", store_id)
print("Updated stored secret id: ", updated_store_id)
>>> Stored secret id: 3c504263-fd3f-40b8-8a1d-9056b7846637
>>> Updated stored secret id: ccdb8036-2635-40d9-9144-2cc89551fce9

update_secrets(cluster_id, store_id, bindings, secrets)​

Update secrets already stored in the Nillion Network.

  • Parameters:
    • cluster_id (str) – UUID of the targeted preprocessing cluster.
    • store_id (str) – The secret’s store ID (returned when calling store_secrets()).
    • bindings (ProgramBindings , optional) – bindings between network parties and the parties are defined by the program.
    • secrets (Secrets) – The secrets to update; this is a hash map indexed by secret IDs.
  • Returns: The unique identifier of this update operation.
  • Return type: str

Example​

updated_secrets = nillion.Secrets({"fortytwo": nillion.SecretInteger(42)})
await client.update_secrets(
    args.cluster_id, store_id, None, updated_secrets
)

user_id​

Returns SDK client’s user ID, which is the public user identifier.

The user ID is used to:

  1. Generate a program ID (identification of a program in the Nillion Network). Check example in store_program();
  2. Grant a user permission to use secrets. Check Permissions.

It is a hash generated from the public key of the user’s key-pair (UserKey). Not to be confused with the party_id which is the generated from the public key of the node’s key-pair (NodeKey).

Read more about user ID in the Nillion Docs.

  • Returns: Client’s user identifier.
  • Return type: str

Example​

print("User ID:", client.user_id)

class py_nillion_client.NodeKey​

This is a NodeKey class that contains a private key used by the underlying libp2p to form multiaddress and identity secrets. This class is consumed by NillionClient class to initialize a client.

This object’s constructors can be used via the following class methods:

  1. From string encoded in Base58 (from_base58());
  2. From a file (from_file());
  3. From a seed (from_seed()).

from_base58()​

Decodes a private key from a string encoded in Base58.

  • Parameters: contents (str) – A base58 string.
  • Return type: NodeKey

Example​

from py_nillion_client import NodeKey
node_key = NodeKey.from_base58(<base 58 encoded data>)

from_file()​

Loads a file containing a private key.

  • Parameters: path (str) – The filesystem path to the file containing a base58 string.
  • Return type: NodeKey

Example​

from py_nillion_client import NodeKey
node_key = NodeKey.from_file('/path/to/nodekey.base58')

from_seed()​

Generates a private key using a seed.

  • Parameters: path (str) – A seed string.
  • Return type: NodeKey

Example​

from py_nillion_client import NodeKey
node_key = NodeKey.from_seed('my_seed')

exception py_nillion_client.PaymentError​

Payment-related errors: missing funds or other errors

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.PaymentsConfig(rpc_endpoint, private_key, chain_id, payments_address, blinding_factor_manager_address)​

This is a PaymentsConfig class used to specify connection parameters for working with the payments network to the nillion client constructor (NillionClient).

  • Parameters:
    • rpc_endpoint (str) – The endpoint to the Optimism node to use.
    • wallet_private_key (str) – The wallet private key to use.
    • chain_id (str) – The chain id.
    • payments_address (str) – The address of the payments smart contract.
    • blinding_factor_manager_address (str) – The address of the blinding factors manager smart contract.
  • Returns: The configuration object.
  • Return type: PaymentsConfig

Example​

import py_nillion_client as nillion

rpc_endpoint = os.getenv("NILLION_BLOCKCHAIN_RPC_ENDPOINT")
wallet_private_key = os.getenv("NILLION_WALLET_PRIVATE_KEY")
chain_id = int(os.getenv("NILLION_CHAIN_ID"))
payments_address = os.getenv("NILLION_PAYMENTS_SC_ADDRESS")
blinding_factor_manager_address = os.getenv("NILLION_BLINDING_FACTORS_MANAGER_SC_ADDRESS")
payments_config = nillion.PaymentsConfig(
          rpc_endpoint,
          wallet_private_key,
          chain_id,
          payments_address,
          blinding_factor_manager_address,
      )

exception py_nillion_client.PermissionError​

Missing permission errors

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.Permissions​

This is a Permissions class used to manage permissions of stored secrets and compute. Permissions need to be set to allow users other than the secret creator to use the secret. This class is used either by NillionClient.store_secrets() or by NillionClient.update_permissions().

The default instantiation of this class is given by the method default_for_user().

Example​

import py_nillion_client as nillion

# Example 1 - Storing a secret
permissions = nillion.Permissions.default_for_user(client.user_id)
permissions.add_retrieve_permissions(set([args.new_user_id]))
secrets = nillion.Secrets({"fortytwo": nillion.SecretInteger(42)})
# new_user_id is able to retrieve "fortytwo"
store_id = await user_client.store_secrets(
  cluster_id, None, secrets, permissions
)

# Example 2 - Updating permissions
permissions.add_update_permissions(set([args.new_user_id]))
# new_user_id is able to update "fortytwo" secret
updated_store_id = await client.update_permissions(args.cluster_id, store_id, permissions)

add_compute_permissions(compute)​

Add compute permissions to the Permissions instance for the user IDs provided.

  • Parameters: compute (dict of set of str) – Dict keyed by the user_id of the targets where the value is a set of str specifying which program IDs to permit compute for.

Example​

import py_nillion_client as nillion

program_id = client.user_id + "/" + "program_name"
permissions = nillion.Permissions.default_for_user(client.user_id)
permissions.add_compute_permissions({
    args.compute_user_id: {program_id},
})

add_delete_permissions(delete)​

Add delete permissions to the Permissions instance for the given set of user IDs

  • Parameters: delete (set of str) – Desired targets to permit delete Secrets.

Example​

import py_nillion_client as nillion

permissions = nillion.Permissions.default_for_user(client.user_id)
permissions.add_delete_permissions(set([args.delete_user_id]))

add_retrieve_permissions(retrieve)​

Add retrieve permissions to the Permissions instance for the given set of user IDs.

  • Parameters: retrieve (set of str) – Desired targets to permit read of stored programs or retrieve Secrets

Example​

import py_nillion_client as nillion

permissions = nillion.Permissions.default_for_user(client.user_id)
permissions.add_retrieve_permissions(set([args.retriever_user_id]))

add_update_permissions(update)​

Add update permissions to the Permissions instance for the given set of user IDs.

  • Parameters: update (set of str) – Desired targets to permit update Secrets.

Example​

import py_nillion_client as nillion

permissions = nillion.Permissions.default_for_user(client.user_id)
permissions.add_update_permissions(set([args.update_user_id]))

static default_for_user(user_id, program=None)​

Returns the default permission set for the given user ID.

Note: this method can be used to clear/revoke permissions previously granted by the user.

  • Parameters:
    • user_id (str) – Desired target user ID.
    • program (str , optional) – Specify a Program ID to apply permission to.
  • Return type: Permissions

Example​

import py_nillion_client as nillion

permissions = nillion.Permissions.default_for_user(client.user_id)

is_compute_allowed(user_id, program)​

Returns true if user has compute permissions for every single program.

  • Return type: bool

Example​

program_id = client.user_id + "/" + "program_name"
compute_allowed = permissions.is_compute_allowed(user_client.user_id, program_id)

is_delete_allowed(user_id)​

Returns true if user has delete permissions.

  • Return type: bool

Example​

import py_nillion_client as nillion

permissions = nillion.Permissions.default_for_user(client.user_id)
delete_allowed = permissions.is_delete_allowed(user_client.user_id)
print("Default user is always allowed: ", delete_allowed)
>>> Default user is always allowed: True

is_retrieve_allowed(user_id)​

Returns true if user has retrieve permissions.

  • Return type: bool

Example​

import py_nillion_client as nillion

permissions = nillion.Permissions.default_for_user(client.user_id)
retrieve_allowed = permissions.is_retrieve_allowed(user_client.user_id)
print("Default user is always allowed: ", retrieve_allowed)
>>> Default user is always allowed: True

is_retrieve_permissions_allowed(user_id)​

Checks if user is allowed to retrieve the permissions.

  • Return type: bool

Example​

retrieve_permissions_allowed = permissions.is_retrieve_permissions_allowed(user_client.user_id)

is_update_allowed(user_id)​

Returns true if user has update permissions.

  • Return type: bool

Example​

import py_nillion_client as nillion

permissions = nillion.Permissions.default_for_user(client.user_id)
update_allowed = permissions.is_update_allowed(user_client.user_id)
print("Default user is always allowed: ", update_allowed)
>>> Default user is always allowed: True

is_update_permissions_allowed(user_id)​

Checks if user is allowed to update the permissions.

  • Return type: bool

Example​

update_permissions_allowed = permissions.is_update_permissions_allowed(user_client.user_id)

class py_nillion_client.PreprocessingConfig​

The PreprocessingConfig class, which contains the configuration of each pre-processing protocol. Currently, it contains:

  1. Alpha;
  2. Lambda;
  3. Comparison;
  4. Division;
  5. Modulo;
  6. Public output equality.

Each protocol returns its instance of PreprocessingProtocolConfig class.

  • Returns: Instance of the PreprocessingConfig class of a cluster.
  • Return type: PreprocessingConfig

Example​

cinfo = await client.cluster_information(args.cluster_id)
cluster_preprocessing_info = cinfo.preprocessing

alpha​

The ALPHA generation protocol configuration.

Example​

cinfo = await client.cluster_information(args.cluster_id)
cinfo.preprocessing.alpha

compare​

The PREP-COMPARE generation protocol configuration.

Example​

cinfo = await client.cluster_information(args.cluster_id)
cinfo.preprocessing.compare

division_integer_secret​

The PREP-DIV-INT-SECRET generation protocol configuration.

Example​

cinfo = await client.cluster_information(args.cluster_id)
cinfo.preprocessing.division_integer_secret

lambda_protocol​

The LAMBDA generation protocol configuration.

Example​

cinfo = await client.cluster_information(args.cluster_id)
cinfo.preprocessing.lambda_protocol

modulo​

The PREP-MODULO generation protocol configuration.

Example​

cinfo = await client.cluster_information(args.cluster_id)
cinfo.preprocessing.modulo

public_output_equality​

The PREP-PUBLIC-OUTPUT-EQUALITY generation protocol configuration.

Example​

cinfo = await client.cluster_information(args.cluster_id)
cinfo.preprocessing.public_output_equality

share_to_particle​

The PREP-SHARE-TO-PARTICLE generation protocol configuration.

truncpr​

The PREP-TRUNCPR generation protocol configuration

class py_nillion_client.PreprocessingProtocolConfig​

The PreprocessingProtocolConfig class, which contains the configuration of a particular protocol.

batch_size​

The number of elements generated on every run.

  • Return type: The number of elements generated on every run of the pre-processing protocol.

Example​

cinfo = await client.cluster_information(args.cluster_id)

print("Batch size for alpha protocol:", cinfo.cinfo.preprocessing.alpha.batch_size)
>>> Batch size for alpha protocol: 1024

class py_nillion_client.ProgramBindings(program_id)​

This is a ProgramBindings class used to bind compute parties to explicit peer IDs (provided by the NillionClient.party_id). Bindings need to be set to use secrets in programs

This class is used by the NillionClient.store_secrets() and NillionClient.compute() methods.

Example​

import py_nillion_client as nillion

bindings = nillion.ProgramBindings(args.program_id)

# Add bindings when storing a secret
bindings.add_input_party("InputPartyName", client.party_id)
secrets = nillion.Secrets({"fortytwo": nillion.SecretInteger(42)})
store_id = await client.store_secrets(
    cluster_id, bindings, secrets, None
)

# Add bindings for compute action
bindings = nillion.ProgramBindings(args.program_id)
bindings.add_input_party("InputPartyName" client.party_id)
bindings.add_output_party("OutputPartyName", client.party_id)
uuid = await client.compute(
    args.cluster_id,
    bindings,
    [store_id],
    args.compute_secrets,
    args.compute_public_variables,
)

add_input_party(name, id)​

Bind an input party with a name to a specific program.

  • Parameters:
    • name (str) – The logical name of the input party in the Nada program.
    • id (str) – The party identifier.

Example​

bindings = nillion.ProgramBindings(args.program_id)
bindings.add_input_party("InputPartyName" client.party_id)

add_output_party(name, id)​

Bind an output party with a name to a specific program.

  • Parameters:
    • name (str) – The logical name of the output party in the Nada program.
    • id (str) – The party identifier.

Example​

bindings = nillion.ProgramBindings(args.program_id)
bindings.add_output_party("OutputPartyName", client.party_id)

exception py_nillion_client.ProgramError​

Program not found or invalid

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.PublicArray(value)​

This is a PublicArray class used to encode a public array of elements.

Note: __len__ method is implemented to allow getting the length of the array.

  • Parameters: value (list) – List of public encoded elements.
  • Returns: Instance of the PublicArray class.
  • Return type: PublicArray
  • Raises: ValueError – invalid public variable type: Raises an error when a secret encoded element is included inside a public array.

Example​

import py_nillion_client as nillion

public_array = nillion.PublicArray([
    py_nillion_client.PublicVariableInteger(1),
    py_nillion_client.PublicVariableInteger(2),
])

print("The length of the array is: ", len(public_array))
>>> The length of the array is: 2

value​

Getter method for the value inside a PublicArray instance.

  • Returns: List of public encoded elements.
  • Return type: list

Example​

print("My public array: \n", public_array.value)
>>> My public array:
>>>  [<builtins.PublicVariableInteger object at 0x7f8c461ce0b0>, <builtins.PublicVariableInteger object at 0x7f8c461ce370>]

class py_nillion_client.PublicVariableInteger(value)​

This is a PublicVariableInteger class used to encode a public variable value as an integer.

Note: __eq__ method is implemented to allow to compare two integers.

Example​

import py_nillion_client as nillion

pub_integer_1 = nillion.PublicVariableInteger(1)
pub_integer_2 = nillion.PublicVariableInteger(2)

print("Are the public integers the same? ", pub_integer_1 == pub_integer_2)
>>> Are the public integers the same?  False

value​

Getter and setter for the value inside a PublicVariableInteger instance.

  • Returns: The value of the public integer.
  • Return type: int

Example​

pub_integer = nillion.PublicVariableInteger(1)
print("Public integer is: ", pub_integer.value)
pub_integer.value = 2
print("Public integer is now: ", pub_integer.value)
>>> Public integer is:  1
>>> Public integer is now:  2

class py_nillion_client.PublicVariableUnsignedInteger(value)​

This is a PublicVariableUnsignedInteger class used to encode a public variable value as an unsigned integer.

Note: __eq__ method is implemented to allow to compare two unsigned integers.

  • Parameters: value (int) – Value of the public encoded element.
  • Returns: Instance of the PublicVariableUnsignedInteger class.
  • Return type: PublicVariableUnsignedInteger
  • Raises: OverflowError – can’t convert negative int to unsigned: Raises an error when a negative integer value is used.

Example​

import py_nillion_client as nillion

pub_uinteger_1 = nillion.PublicVariableUnsignedInteger(1)
pub_uinteger_2 = nillion.PublicVariableUnsignedInteger(2)

print("Are the public unsigned integers the same? ", pub_uinteger_1 == pub_uinteger_2)
>>> Are the public unsigned integers the same?  False

value​

Getter and setter for the value inside a PublicVariableUnsignedInteger instance.

  • Returns: The value of the public unsigned integer.
  • Return type: int

Example​

pub_uinteger = nillion.PublicVariableUnsignedInteger(1)
print("Public unsigned integer is: ", pub_uinteger.value)
pub_uinteger.value = 2
print("Public unsigned integer is now: ", pub_uinteger.value)
>>> Public unsigned integer is:  1
>>> Public unsigned integer is now:  2

class py_nillion_client.PublicVariables(public_variables)​

This is a PublicVariables class used as a collection of public variables. It can contain:

  1. Public integers (PublicVariableInteger);
  2. Public unsigned integers (PublicVariableUnsignedInteger);
  3. Public arrays (PublicArray).

This class is used by the NillionClient.compute() method to pass the public variables used by the corresponding Nada program.

  • Parameters: public_variables (dict) – Where the key is a named str and the value is an encoded value created from accompanying encoders.
  • Returns: Instance of the PublicVariables class.
  • Return type: PublicVariables
  • Raises: ValueError – invalid public variable type: Raises an error when a secret variable element is included inside the public_variables dictionary.

Example​

import py_nillion_client as nillion

pub_uinteger = nillion.PublicVariableUnsignedInteger(1)
pub_integer = nillion.PublicVariableInteger(2)
public_array = nillion.PublicArray([
    nillion.PublicVariableInteger(3),
    nillion.PublicVariableInteger(4),
])

public_variables = nillion.PublicVariables({
    "pub_uinteger": pub_uinteger,
    "pub_integer": pub_integer,
    "public_array": public_array
})

dict()​

Returns the stored public variables as a dictionary.

  • Returns: Native python dictionary with mapped encoded values.
  • Return type: dict

Example​

public_variables = nillion.PublicVariables({
    "pub_uinteger": pub_uinteger,
    "pub_integer": pub_integer,
    "public_array": public_array
})

print("Public variables:\n", public_variables.dict())
>>> Public variables:
>>> {'pub_uinteger': <builtins.PublicVariableUnsignedInteger object at 0x7f2c3a2a9b30>, 'pub_integer': <builtins.PublicVariableInteger object at 0x7f2c3a2b6db0>, 'public_array': <builtins.PublicArray object at 0x7f2c3a2b1d90>}

exception py_nillion_client.ResultError​

Errors related to fetching computation results

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.SecretArray(value)​

This is a SecretArray class used to encode a secret array of elements.

Note: __len__ method is implemented to allow getting the length of the array.

  • Parameters: value (list) – List of secret encoded elements.
  • Returns: Instance of the SecretArray class.
  • Return type: SecretArray
  • Raises: ValueError – invalid secret type: Raises an error when a public encoded element is included inside a secret array.

Example​

import py_nillion_client as nillion

secret_array = nillion.SecretArray([
    py_nillion_client.SecretInteger(1),
    py_nillion_client.SecretInteger(2),
)

print("The length of the array is: ", len(secret_array))
>>> The length of the array is: 2

value​

Getter method for the value inside a SecretArray instance.

  • Returns: List of secret encoded elements.
  • Return type: list

Example​

print("My secret array: \n", secret_array.value)
>>> My secret array:
>>>  [<builtins.SecretInteger object at 0x7f8c38e2a6f0>, <builtins.SecretInteger object at 0x7f8c38e29930>]

class py_nillion_client.SecretBlob(value)​

This is a SecretBlob class used to encode a secret as a blob.

Note: __eq__ method is implemented to allow to compare two blobs.

  • Parameters: value (bytearray) – Value of the secret blob as a bytearray.
  • Returns: Instance of the SecretBlob class.
  • Return type: SecretBlob
  • Raises: VTypeError – argument ‘value’: Raises an error when a non-bytearray object is provided.

Example​

import py_nillion_client as nillion

gm_blob_ba = bytearray("gm, builder!", "utf-8")
gm_blob = py_nillion_client.SecretBlob(gm_blob_ba)
ready_blob_ba = bytearray("ready to build!", "utf-8")
ready_blob = py_nillion_client.SecretBlob(ready_blob_ba)

print("Are these blobs the same?", gm_blob == ready_blob)
>>> Are these blobs the same?  False

value​

Getter and setter for the value inside a SecretBlob instance.

  • Returns: The value of the secret blob.
  • Return type: int

Example​

gm_blob_ba = bytearray("gm, builder!", "utf-8")
blob = nillion.SecretBlob(gm_blob_ba)
print("Blob is: ", blob.value)
ready_blob_ba = bytearray("ready to build!", "utf-8")
blob.value = ready_blob_ba
print("Blob is now: ", blob.value)
>>> Blob is:  bytearray(b'gm, builder!')
>>> Blob is now:  bytearray(b'ready to build!')

class py_nillion_client.SecretInteger(value)​

This is a SecretInteger class used to encode a secret as a integer.

Note: __eq__ method is implemented to allow to compare two integers.

  • Parameters: value (int) – Value of the secret encoded element.
  • Returns: Instance of the SecretInteger class.
  • Return type: SecretInteger

Example​

import py_nillion_client as nillion

sec_integer_1 = nillion.SecretInteger(1)
sec_integer_2 = nillion.SecretInteger(2)

print("Are the secret integers the same? ", sec_integer_1 == sec_integer_2)
>>> Are the secret integers the same?  False

WARNING​

Providing zero as SecretInteger leaks information.

value​

Getter and setter for the value inside a SecretInteger instance.

  • Returns: The value of the secret integer.
  • Return type: int

Example​

sec_integer = nillion.SecretInteger(1)
print("Secret integer is: ", sec_integer.value)
sec_integer.value = 2
print("Secret integer is now: ", sec_integer.value)
>>> Secret integer is:  1
>>> Secret integer is now:  2

class py_nillion_client.SecretUnsignedInteger(value)​

This is a SecretUnsignedInteger class used to encode a secret as an unsigned integer.

Note: __eq__ method is implemented to allow to compare two unsigned integers.

  • Parameters: value (int) – Value of the secret encoded element.
  • Returns: Instance of the SecretUnsignedInteger class.
  • Return type: SecretUnsignedInteger
  • Raises: OverflowError – can’t convert negative int to unsigned: Raises an error when a negative integer value is used.

Example​

import py_nillion_client as nillion

sec_uinteger_1 = nillion.SecretUnsignedInteger(1)
sec_uinteger_2 = nillion.SecretUnsignedInteger(2)

print("Are the public unsigned integers the same? ", sec_uinteger_1 == sec_uinteger_2)
>>> Are the secret unsigned integers the same?  False

WARNING​

Providing zero as SecretUnsignedInteger leaks information.

value​

Getter and setter for the value inside a SecretUnsignedInteger instance.

  • Returns: The value of the secret unsigned integer.
  • Return type: int

Example​

sec_uinteger = nillion.SecretUnsignedInteger(1)
print("Secret unsigned integer is: ", sec_uinteger.value)
sec_uinteger.value = 2
print("Secret unsigned integer is now: ", sec_uinteger.value)
>>> Secret unsigned integer is:  1
>>> Secret unsigned integer is now:  2

class py_nillion_client.Secrets(secrets)​

This is a Secrets class used to hold secrets. It can contain:

  1. Secret integers (SecretInteger);
  2. Secret unsigned integers (SecretUnsignedInteger);
  3. Secret arrays (SecretArray).

This class is used by the NillionClient.compute() method to pass the secrets used by the corresponding Nada program that are not stored.

  • Parameters: secrets (dict) – A map of named encoded secret values to store
  • Returns: Instance of the Secrets class.
  • Return type: Secrets
  • Raises: ValueError – invalid public variable type: Raises an error when a public variable element is included inside the secrets dictionary.

Example​

import py_nillion_client as nillion

sec_uinteger = nillion.SecretUnsignedInteger(1)
sec_integer = nillion.SecretInteger(1)
sec_array = nillion.SecretArray([
    nillion.SecretInteger(1),
    nillion.SecretInteger(2),
])

secrets = nillion.Secrets({
    "sec_uinteger": sec_uinteger,
    "sec_integer": sec_integer,
    "sec_array": sec_array
 })

dict()​

Returns the stored secrets as a dictionary.

  • Returns: Native python dictionary with mapped encoded values
  • Return type: dict

Example​

secrets = nillion.Secrets({
    "sec_uinteger": sec_uinteger,
    "sec_integer": sec_integer,
    "sec_array": sec_array
 })

print("Secrets:\n", secrets.dict())
>>> Secrets:
>>>  {'sec_array': <builtins.SecretArray object at 0x7f2ede3d9e80>, 'sec_uinteger': <builtins.SecretUnsignedInteger object at 0x7f2ee201a850>, 'sec_integer': <builtins.SecretInteger object at 0x7f2ede3df3f0>}

exception py_nillion_client.TimeoutError​

Timed out

args​

with_traceback()​

Exception.withtraceback(tb) – set self._traceback__ to tb and return self.

class py_nillion_client.UserKey​

This is a UserKey class that contains the public and private keys for the user. This class is used by NillionClient class to initialize a client.

This object’s constructors can be used via the following class methods:

  1. From string encoded in Base58 (from_base58());
  2. From a file (from_file());
  3. From scratch (generate());
  4. From seed (seed()).

from_base58()​

Loads public and private key from base 58 encoded data.

  • Parameters: contents (str) – A base58 string.
  • Return type: UserKey

Example​

from py_nillion_client import UserKey
user_key = UserKey.from_base58(<base 58 encoded data>)

from_file()​

Loads public and private key from a file.

  • Parameters: path (str) – The filesystem path to the file containing a base58 string.
  • Return type: UserKey

Example​

from py_nillion_client import UserKey
user_key = UserKey.from_file('/path/to/userkey.base58')

from_seed()​

Generates a public and private key from a seed.

  • Parameters: seed (str) – A seed string.
  • Return type: UserKey

Example​

from py_nillion_client import UserKey
user_key = UserKey.from_seed('my_seed')

generate()​

Generates a random public and private key.

Example​

from py_nillion_client import UserKey
user_key = UserKey.generate()

py_nillion_client.version()​

Return the version of this SDK client.

  • Returns: The version of this build.
  • Return type: str

Example​

py_nillion_client.version()