Skip to main content

Client Reference

Nillion client.

class nillion_client.Array(value)​

This is a Array 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 Array class.
  • Return type: Array
  • Raises: ValueError – invalid secret type: Raises an error when a public encoded element is included inside a secret array.

Example​

from nillion_client import Array, SecretInteger

secret_array = Array([ SecretInteger(1), 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 Array instance.

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

Example​

print("My secret array: \n", secret_array.value)
>>> My secret array:
>>>  [SecretInteger(1), SecretInteger(2)]

class nillion_client.Boolean(value)​

This is a Boolean class used to encode a public variable value as an boolean.

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

Example​

from nillion_client import Boolean

pub_boolean_1 = Boolean(True)
pub_boolean_2 = Boolean(False)

print("Are the public booleans the same? ", pub_boolean_1 == pub_boolean_2)
>>> Are the public booleans the same?  False

value​

nillion_client.ComputeId​

alias of UUID

class nillion_client.EcdsaDigestMessage(value)​

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

  • Parameters: value (bytearray) – Value of the secret blob as a bytearray.
  • Returns: Instance of the EcdsaDigestMessage class.
  • Return type: EcdsaDigestMessage
  • 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 = nillion.EcdsaDigestMessage(gm_blob_ba)
ready_blob_ba = bytearray("ready to build!", "utf-8")
ready_blob = nillion.EcdsaDigestMessage(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 EcdsaDigestMessage instance.

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

Example​

gm_blob_ba = bytearray("gm, builder!", "utf-8")
blob = nillion.EcdsaDigestMessage(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 nillion_client.EcdsaPrivateKey(value)​

This is a EcdsaPrivateKey class used to encode a secret bytearray as an ecdsa private key.

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

Example​

from nillion_client import EcdsaPrivateKey
import os

pk1_bytes = bytearray(os.urandom(32))
pk1 = EcdsaPrivateKey(pk1_bytes)
pk2_bytes = bytearray(os.urandom(32))
pk2 = EcdsaPrivateKey(pk2_bytes)

print("Are these ecdsa private keys the same?", pk1 == pk2)
>>> Are these ecdsa private keys the same?  False

value​

Getter and setter for the value inside a EcdsaPrivateKey instance.

  • Returns: The value of the private ecdsa key.
  • Return type: int

Example​

ecdas_pk_ba = bytearray(b'these are not random 32 bytes!!!')
ecdsa_pk = EcdsaPrivateKey(ecdas_pk_ba)
print("Ecdsa private key is: ", ecdsa_pk.value)
ecdsa_pk_ba_prime = bytearray(b'these are good random 32 bytes!!')
ecdsa_pk.value = ecdsa_pk_ba_prime
print("Ecdsa private key is now: ", ecdsa_pk.value)
>>> Ecdsa private key is:  bytearray(b'these are not random 32 bytes!!!')
>>> Ecdsa private key is now:  bytearray(b'these are good random 32 bytes!!')

class nillion_client.EcdsaSignature(value)​

This is a EcdsaSignature class used to encode a secret bytearray as an ecdsa private key.

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

Example​

from nillion_client import EcdsaSignature
import os

r = bytearray(os.urandom(32))
s = bytearray(os.urandom(32))
sig = EcdsaSignature((r, s))

value​

Getter for the r inside a EcdsaSignature instance.

  • Returns: The value of the private ecdsa key.
  • Return type: int

Example​

from nillion_client import EcdsaSignature
import os

r = bytearray(os.urandom(32))
s = bytearray(os.urandom(32))
signature = EcdsaSignature((r, s))
print("Ecdsa signature is: ", signature.value)

class nillion_client.InputPartyBinding(party_name, user)​

Represents the binding of a named input party in a program to a user id

static from_proto(proto)​

Constructs an instance from its protobuf representation

party_name : str​

to_proto()​

Converts an instance to its protobuf representation

  • Return type: InputPartyBinding

user : UserId​

class nillion_client.Integer(value)​

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

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

Example​

from nillion_client import Integer

pub_integer_1 = Integer(1)
pub_integer_2 = Integer(2)

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

value​

exception nillion_client.InternalError​

Exception raised for internal errors in the library.

args​

with_traceback()​

Exception.with_traceback(tb) – set self._traceback_ to tb and return self.

class nillion_client.Network(chain_id, chain_grpc_endpoint, nilvm_grpc_endpoint)​

The network class contains network settings for the VmClient.

chain_grpc_endpoint : str​

chain_id : str​

classmethod devnet(nilvm_grpc_endpoint, chain_grpc_endpoint)​

Initializes a network configuration compatible with a Nillion devnet.

By default the devnet starts without any SSL configuration so all of the tls_* parameters are not required.

  • Parameters:
    • nilvm_grpc_endpoint (str) – The Nillion network bootnode endpoint.
    • chain_grpc_endpoint (str) – The nilchain gRPC endpoint.
  • Return type: Network

Example​

config = Network.devnet(
    nilvm_grpc_endpoint="http://127.0.0.1:37939",
    chain_grpc_endpoint="localhost:26649",
)

classmethod from_config(network_name)​

Load a network configuration from the filesystem.

This looks up a network configuration under ~/.config/nillion/networks. This allows easily loading pre-existing network configurations, like the one dumped by nillion-devnet when it starts.

  • Parameters: network_name (str) – The name of the network to be loaded.
  • Return type: Network

Example​

config = Network.from_config("devnet")

nilvm_grpc_endpoint : str​

class nillion_client.NilChainPayer(network, wallet_private_key, gas_limit, wallet_prefix='nillion', query_timeout_seconds=30)​

A payer that uses the nilchain to perform payments.

static prepare_msg(resource, address, amount)​

Create a MsgPayFor transaction.

  • Parameters:
    • resource (bytes) – The resource to pay for.
    • address (str) – The address of the payment sender.
    • amount (int) – The amount of unil that needs to be paid.
  • Return type: MsgPayFor

async submit_payment(amount, resource, gas_limit=None)​

Submits a payment to the chain.

This must submit a MsgPayFor transaction in nilchain using the given resource as a parameter.

  • Parameters:
    • amount (int) – The amount of unil that needs to be paid.
    • resource (bytes) – The resource to pay for.
    • gas_limit (Optional[int]) – The gas limit to set for this operation.
  • Return type: str

property wallet_address : str​

Get the address associated with the payer’s wallet.

nillion_client.NilChainPrivateKey​

alias of PrivateKey

exception nillion_client.NotFoundError​

Exception raised when values are not found.

args​

with_traceback()​

Exception.with_traceback(tb) – set self._traceback_ to tb and return self.

class nillion_client.OutputPartyBinding(party_name, users)​

Represents the binding of a named output party in a program to a user id

static from_proto(proto)​

Constructs an instance from its protobuf representation

party_name : str​

to_proto()​

Converts an instance to its protobuf representation

  • Return type: OutputPartyBinding

users : List[UserId]​

class nillion_client.Payer​

An abstraction over the mechanism to perform payments for operations in the Nillion network.

static prepare_msg(resource, address, amount)​

Create a MsgPayFor transaction.

  • Parameters:
    • resource (bytes) – The resource to pay for.
    • address (str) – The address of the payment sender.
    • amount (int) – The amount of unil that needs to be paid.
  • Return type: MsgPayFor

abstract async submit_payment(amount, resource, gas_limit=None)​

Submits a payment to the chain.

This must submit a MsgPayFor transaction in nilchain using the given resource as a parameter.

  • Parameters:
    • amount (int) – The amount of unil that needs to be paid.
    • resource (bytes) – The resource to pay for.
    • gas_limit (Optional[int]) – The gas limit to set for this operation.
  • Return type: str

exception nillion_client.PermissionDeniedError​

Exception raised a permission to run an operation has been denied.

args​

with_traceback()​

Exception.with_traceback(tb) – set self._traceback_ to tb and return self.

class nillion_client.Permissions(owner, retrieve=<factory>, update=<factory>, delete=<factory>, compute=<factory>)​

The permissions associated with a set of stored values.

allow_compute(user_id, program_id)​

Allow a user to use these values on an execution of the given program id.

allow_delete(user_id)​

Allow a user to delete these values.

allow_retrieve(user_id)​

Allow a user to retrieve these values.

allow_update(user_id)​

Allow a user to update these values.

compute : ComputePermissions​

classmethod defaults_for_user(user_id)​

Returns a Permissions object with update, retrieve and delete permissions for a user.

delete : Set[UserId]​

classmethod from_proto(proto)​

Create a Permissions instance from a ProtoPermissions message.

owner : UserId​

retrieve : Set[UserId]​

to_proto()​

Convert this Permissions instance to a ProtoPermissions message.

  • Return type: Permissions

update : Set[UserId]​

class nillion_client.PermissionsDelta(retrieve=<factory>, update=<factory>, delete=<factory>, compute=<factory>)​

A delta of permission grants/revokes to be applied

compute : ComputePermissionCommand​

delete : PermissionCommand​

retrieve : PermissionCommand​

update : PermissionCommand​

class nillion_client.PreprocessingElement(value: int)​

A preprocessing element.

as_integer_ratio()​

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

bit_count()​

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

bit_length()​

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

conjugate()​

Returns self, the complex conjugate of any int.

denominator​

the denominator of a rational number in lowest terms

from_bytes(byteorder, *, signed=False)​

Return the integer represented by the given array of bytes.

bytes : Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder : The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use


`

sys.byteorder’ as the byte order value.

signed : Indicates whether two’s complement is used to represent the integer.

classmethod from_string()​

Return the value which corresponds to the string name.

  • Parameters: name (str) – The name of the enum member to get.
  • Raises: ValueError – The member was not found in the Enum.
  • Return type: Self

imag​

the imaginary part of a complex number

name : Optional[str]​

numerator​

the numerator of a rational number in lowest terms

real​

the real part of a complex number

to_bytes(length, byteorder, *, signed=False)​

Return an array of bytes representing an integer.

length : Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.

byteorder : The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use


`

sys.byteorder’ as the byte order value.

signed : Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

classmethod try_value()​

Return the value which corresponds to the value.

  • Parameters: value (int) – The value of the enum member to get.
  • Returns: The corresponding member or a new instance of the enum if value isn’t actually a member.
  • Return type: Enum

value : int​

class nillion_client.PrivateKey(privkey=None, raw=True)​

deserialize(privkey_ser)​

ecdsa_deserialize(ser_sig)​

ecdsa_deserialize_compact(ser_sig)​

ecdsa_recover(msg, recover_sig, raw=False, digest=<built-in function openssl_sha256>)​

ecdsa_recoverable_convert(recover_sig)​

ecdsa_recoverable_deserialize(ser_sig, rec_id)​

ecdsa_recoverable_serialize(recover_sig)​

ecdsa_serialize(raw_sig)​

ecdsa_serialize_compact(raw_sig)​

ecdsa_sign(msg, raw=False, digest=<built-in function openssl_sha256>, custom_nonce=None)​

ecdsa_sign_recoverable(msg, raw=False, digest=<built-in function openssl_sha256>)​

ecdsa_signature_normalize(raw_sig, check_only=False)​

Check and optionally convert a signature to a normalized lower-S form. If check_only is True then the normalized signature is not returned.

This function always return a tuple containing a boolean (True if not previously normalized or False if signature was already normalized), and the normalized signature. When check_only is True, the normalized signature returned is always None.

schnorr_sign(msg, bip340tag, raw=False)​

serialize()​

set_raw_privkey(privkey)​

tweak_add(scalar)​

Tweak the current private key by adding a 32 byte scalar to it and return a new raw private key composed of 32 bytes.

tweak_mul(scalar)​

Tweak the current private key by multiplying it by a 32 byte scalar and return a new raw private key composed of 32 bytes.

nillion_client.ProgramId​

alias of str

class nillion_client.SecretBlob(value)​

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

  • 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​

from nillion_client import SecretBlob

gm_blob_ba = bytearray("gm, builder!", "utf-8")
gm_blob = SecretBlob(gm_blob_ba)
ready_blob_ba = bytearray("ready to build!", "utf-8")
ready_blob = 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 = 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 nillion_client.SecretBoolean(value)​

This is a SecretBoolean class used to encode a secret as a boolean.

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

Example​

from nillion_client import SecretBoolean

sec_bool_1 = SecretBoolean(True)
sec_bool_2 = SecretBoolean(False)

print("Are the secret booleans the same? ", sec_bool_1 == sec_bool_2)
>>> Are the secret booleans the same?  False

value​

class nillion_client.SecretInteger(value)​

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

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

Example​

from nillion_client import SecretInteger

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

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

value​

class nillion_client.SecretUnsignedInteger(value)​

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

  • 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​

from nillion_client import SecretUnsignedInteger

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

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

value​

class nillion_client.UnsignedInteger(value)​

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

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

Example​

from nillion_client import UnsignedInteger

pub_uinteger_1 = UnsignedInteger(1)
pub_uinteger_2 = UnsignedInteger(2)

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

value​

class nillion_client.UserId(contents)​

A user identifier.

User identifiers are derived from the public key used for authentication when performing operations in the network. User identifiers are non sensitive and can be shared with other users.

contents : bytes​

classmethod from_proto(proto)​

Create a user identifier instance from its protobuf representation.

static from_public_key(public_key)​

Creates a user identifier from a public key.

User identifiers are defined as the last 20 bytes of the SHA256 hash of the public key.

  • Return type: UserId
  • Returns: The user id.

Example​

import secp256k1

private_key = secp256k1.PrivateKey()
user = UserId.from_public_key(private_key.pubkey)

static parse(hex_bytes)​

Parse a user identifier from a hex encoded string.

  • Parameters: hex_bytes (str) – The hex bytes that represent the user id.
  • Return type: UserId
  • Returns: The parsed user id.

Example​

user = UserId.parse("3113a1170de795e4b725b84d1e0b4cfd9ec58ce9")

to_proto()​

Convert a user identifier to its protobuf representation.

  • Return type: UserId

nillion_client.ValuesId​

alias of UUID

class nillion_client.VmClient(key, network, payer, payment_mode, _raise_if_called=True)​

A class to interact with the Nillion network.

This class allows performing all operations on the Nillion network, such as storing and retrieving secrets, uploading programs, invoking computations, etc.

Example​

import os
from nillion_client import PrivateKey, Network, NilChainPayer, NilChainPrivateKey, VmClient

# The private key that will represent the identity of the user performing actions in the network.
private_key = PrivateKey()

# Load the config dumped by the `nillion-devnet` automatically on start and use it as the network.
network = Network.from_config("devnet")

# The payer that will be used to pay for operations in the network.
nilchain_private_key = os.getenv("NILLION_NILCHAIN_KEY")
chain_client = NilChainPayer(
    network,
    wallet_private_key=NilChainPrivateKey(bytes.fromhex(nilchain_private_key)),
    gas_limit=10000000,
)

# Finally, create the client
client = await VmClient.create(private_key, network, payer)

async add_funds(amount_unil, target_user=None)​

Add funds to a user’s account on the nillion network.

By default this will fund the account tied to the user this client is currently using.

Funds will be automatically used when performing payments unless the payment mode in the client is changed.

NOTE​

Funds will expire after 30 days regardless of use so don’t add more funds than you intend to use in the short term

async balance()​

Gets the balance associated with the user’s account in the network.

This balance will be preferred when running operations and can be topped up by calling VmClient.add_funds().

  • Return type: AccountBalanceResponse

close()​

Closes the client and releases all resources associated with it.

cluster : Cluster​

The cluster definition that this client is using.

compute(program_id, input_bindings, output_bindings, values, value_ids=None)​

Invokes a computation.

This operation returns immediately as soon as all initial validations for the program invocation are performed.

The results for a computation should be fetched by output parties via the VmClient.retrieve_compute_results() function.

The name of the input and output parties must match the defined parties in the program being invoked.

Example​

values = {
    "foo": SecretInteger(40),
    "bar": SecretInteger(2),
}

# Invoke a program using the given input and output bindings. In this case we are the only party providing
# inputs and we are the only party receiving outputs.
compute_id = await client.compute(
    program_id,
    input_bindings=[
        nillion_client.InputPartyBinding(party_name="Party1", user=client.user_id)
    ],
    output_bindings=[
        nillion_client.OutputPartyBinding(
            party_name="Party1", users=[client.user_id]
        )
    ],
    values=values,
).invoke()

# Now fetch the results.
results = await client.retrieve_compute_results(compute_id).invoke()

async classmethod create(key, network, payer, payment_mode=PaymentMode.FROM_BALANCE)​

Create a new Nillion client.

  • Parameters:
    • key (PrivateKey) – The private key that will represent the client’s identity in the network.
    • network (Network) – The network the client should connect to.
    • payer (Payer) – The payer that will pay for all operations performed in the network.
  • Return type: VmClient

Example​

client = await VmClient.create(private_key, network, payer)

delete_values(values_id)​

Deletes the values with the given identifier.

This operation requires the user to have “delete” permissions on the given values identifier.

  • Parameters: values_id (UUID) – The identifier of the uploaded values that should be deleted.
  • Return type: DeleteValuesOperation
  • Returns: An operation that once invoked will delete the stored values.

Example​

await client.delete_values(values_id).invoke()

async get_payment_receipt(signed_quote, tx_hash)​

Request to get a payment receipt for a paid operation.

  • Parameters:
    • signed_quote (SignedQuote) – The quote to get a payment receipt for.
    • tx_hash (str | None) – The transaction hash where the payment was made.
  • Return type: SignedReceipt
  • Returns: A signed receipt that can be used to prove to all nodes that the payment was made.

async invoke_compute(receipt, input_bindings, output_bindings, values, value_ids=None)​

Invokes a compute operation in the network.

  • Parameters:
  • Return type: UUID
  • Returns: An identifier for the compute operation.

Example​

values = {
    "foo": SecretInteger(40),
    "bar": SecretInteger(2),
}

# Invoke a program using the given input and output bindings. In this case we are the only party providing
# inputs and we are the only party receiving outputs.
compute_id = await client.compute(
    program_id,
    input_bindings=[
        nillion_client.InputPartyBinding(party_name="Party1", user=client.user_id)
    ],
    output_bindings=[
        nillion_client.OutputPartyBinding(
            party_name="Party1", users=[client.user_id]
        )
    ],
    values=values,
).invoke()

# Now fetch the results.
results = await client.retrieve_compute_results(receipt, compute_id).invoke()

NOTE​

users should use generally use VmClient.compute() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_delete_values(values_id)​

Invoke a delete values operation in the network.

  • Parameters:
    • receipt – A receipt that proves the payment was made.
    • values_id (UUID) – The identifier of the uploaded values that should be deleted.
  • Return type: None

Example​

await client.delete_values(receipt, values_id).invoke()

NOTE​

users should use generally use VmClient.delete_values() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_overwrite_permissions(receipt, permissions)​

Invokes an overwrite permissions operation for the given values id.

  • Parameters:
    • receipt (SignedReceipt) – A receipt that proves the payment was made.
    • values_id – The identifier of the uploaded values for which permissions should be updated.
    • permissions (Permissions) – The permissions to be set.

Example​

permissions = Permissions.default_for_user(user_id)
await client.overwrite_permissions(receipt, values_id, permissions).invoke()

NOTE​

users should use generally use VmClient.overwrite_permissions() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_pool_status(receipt)​

Invokes a preprocessing pool status operation in the network.

  • Parameters:
    • receipt (SignedReceipt) – A receipt that proves the payment was made.
    • note: ( ..) – users should use generally use VmClient.pool_status() unless the API provided by: that function doesn’t satisfy their use cases.
  • Return type: List[PreprocessingOffsets]

async invoke_retrieve_compute_results(compute_id)​

Invoke a retrieve compute results operation in the network.

Example​

results = await client.retrieve_compute_results(receipt, compute_id).invoke()

NOTE​

users should use generally use VmClient.retrieve_compute_results() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_retrieve_permissions(receipt)​

Invokes a retrieve permissions operation in the network.

  • Parameters:
    • receipt (SignedReceipt) – A receipt that proves the payment was made.
    • values_id – The identifier of the uploaded values for which permissions should be retrieved.
  • Return type: Permissions
  • Returns: The set of permissions currently associated with the values.

Example​

await client.retrieve_permissions(receipt, values_id).invoke()

NOTE​

users should use generally use VmClient.retrieve_permissions() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_retrieve_values(receipt)​

Invokes a retrieve values operation.

Example​

await client.retrieve_values(receipt, values_id).invoke()

NOTE​

users should use generally use VmClient.retrieve_values() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_store_program(receipt, program)​

Invokes a store program operation in the network.

  • Parameters:
    • receipt (SignedReceipt) – A receipt that proves the payment was made.
    • program_name – The name of the program being uploaded.
    • program (bytes) – The contents of the .nada.bin file generated from an invocation to pynadac.
  • Return type: str
  • Returns: The stored program’s identifier.

Example​

contents = open("/tmp/program.nada.bin", "rb").read()
await client.store_program(receipt, program_name="my-test-program", program=contents).invoke()

NOTE​

users should use generally use VmClient.store_program() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_store_values(receipt, values, permissions=None, update_identifier=None)​

Invoke a store values operation in the network.

  • Parameters:
  • Return type: UUID
  • Returns: The identifier for the uploaded values.

Example​

values = {
    "foo": SecretInteger(42),
    "bar": Integer(1337),
}
await client.store_values(receipt, values, ttl_days=1).invoke()

NOTE​

users should use generally use VmClient.store_values() unless the API provided by that function doesn’t satisfy their use cases.

async invoke_update_permissions(receipt, delta)​

Invokes an updates the permissions on the given values.

  • Parameters:
    • receipt (SignedReceipt) – A receipt that proves the payment was made.
    • values_id – The identifier of the uploaded values for which permissions should be updated.
    • delta (PermissionsDelta) – The permissions to be granted and revoked.

Example​

# Grant permissions to retrieve these values to `other_user_id`.
delta = PermissionsDelta(retrieve=PermissionCommand(grant=set([other_user_id])))
await client.update_permissions(receipt, values_id, delta).invoke()

NOTE​

users should use generally use VmClient.update_permissions() unless the API provided by that function doesn’t satisfy their use cases.

network : Network​

The network used by this client.

overwrite_permissions(values_id, permissions)​

Overwrites the permissions on the given values id.

This operation requires the user to have “update” permissions on the given values identifier.

  • Parameters:
    • values_id (UUID) – The identifier of the uploaded values for which permissions should be updated.
    • permissions (Permissions) – The permissions to be set.
  • Return type: An operation that once invoked will overwrite the permissions for the given values.

Example​

permissions = Permissions.default_for_user(user_id)
await client.overwrite_permissions(values_id, permissions).invoke()

payment_mode : PaymentMode​

The payment mode to be used.

pool_status()​

Fetch the preprocessing pool status.

  • Return type: PayableOperation[List[PreprocessingOffsets]]
  • Returns: The available offsets for every preprocessing element.

Example​

offsets = await client.pool_status(compute_id)

async request_quote(operation)​

Requests a quote for an operation.

Users should generally not use this function directly and should instead use the concrete function for the action they’re trying to perform, such as VmClient.store_values(),

  • Return type: SignedQuote

retrieve_compute_results(compute_id)​

Retrieve the results of a compute operation.

If the compute operation has finished, this will return the result immediately. If the operation is still ongoing, this will block until the operation finishes.

The invoker user must have been set as an output binding in the VmClient.compute() invocation. If the invoker was bound as an output party, it will only retrieve the subset of the outputs that belong to it based on the configured bindings.

  • Parameters: compute_id (UUID) – The identifier of the compute instance to fetch the results for.
  • Return type: RetrieveComputeResultsOperation
  • Returns: An operation that once invoked will return the result of the computation.

Example​

results = await client.retrieve_compute_results(compute_id).invoke()

retrieve_permissions(values_id)​

Retrieves the permissions for the given values identifier.

This operation requires the user to have “retrieve” permissions on the given values identifier.

  • Parameters: values_id (UUID) – The identifier of the uploaded values for which permissions should be retrieved.
  • Return type: PayableOperation[Permissions]
  • Returns: An operation that once invoked will retrieve the set of permissions currently associated with the values.

Example​

await client.retrieve_permissions(values_id).invoke()

retrieve_values(values_id)​

Retrieves the values with the given identifier, performing unmasking to recover any secrets in the given set of values.

This operation requires the user to have “retrieve” permissions on the given values identifier.

Example​

await client.retrieve_values(values_id).invoke()

store_program(program_name, program)​

Stores a program in the network.

Stored programs can by default be invoked by anyone, although their identifier is only known to the invoker and node operators.

  • Parameters:
    • program_name (str) – The name of the program being uploaded.
    • program (bytes) – The contents of the .nada.bin file generated from an invocation to pynadac.
  • Return type: PayableOperation[str]
  • Returns: An operation that once invoked will return an identifier that can be used to reference this program in invocations to compute and when setting up values permissions for compute operations.

Example​

contents = open("/tmp/program.nada.bin", "rb").read()
await client.store_program(program_name="my-test-program", program=contents).invoke()

store_values(values, ttl_days, permissions=None, update_identifier=None)​

Store a set of values in the network.

Any secret values will be masked automatically before uploading them.

  • Parameters:
  • Return type: PayableOperation[UUID]
  • Returns: An operation that once invoked returns an identifier that uniquely identifies the uploaded values.

Example​

values = {
    "foo": SecretInteger(42),
    "bar": Integer(1337),
}
await client.store_values(values, ttl_days=1).invoke()

update_permissions(values_id, delta)​

Updates the permissions on the given values id with the given delta. As opposed to VmClient.overwrite_permissions(), this operation allows granting and revoking individual permissions without overwriting the entire set.

This operation can only be invoked by the owner of the stored values.

  • Parameters:
    • values_id (UUID) – The identifier of the uploaded values for which permissions should be updated.
    • delta (PermissionsDelta) – The permissions to be granted and revoked.
  • Return type: An operation that once invoked will update the permissions for the given values.

Example​

# Grant permissions to retrieve these values to `other_user_id`.
delta = PermissionsDelta(retrieve=PermissionCommand(grant=set([other_user_id])))
await client.update_permissions(values_id, delta).invoke()

user_id : UserId​

The user identifier associated with this client.