🆕 Nillion SDK Release v0.8.0

[crypblizz8]

TL;DR

Nillion SDK and Python Client release v0.8.0 introduces ECDSA signature support for signing messages with stored private keys, plus a new top-up payment system that makes running multiple operations more efficient. This release also includes CLI improvements with standardized outputs and enhanced permission management.

What's new

🔐 ECDSA Signatures (Python Client)

• Store private keys and sign messages on Nillion
• Use the built-in program: builtin/tecdsa_sign to sign messages with stored private keys
• Check out Nillion Signature Tools, a live demo app for signing messages with private keys stored in Nillion and verifying signatures

💳 Top-up Payments (Python Client)

• Pre-fund your client for multiple operations
• Improved app performance - a single payment covers multiple transactions

🛠️ CLI Enhancements

• New update-permissions command for access control
• Standardized YAML/JSON outputs (Breaking Change)
• Improved node compatibility checks and logging issues fixes

📋 How to upgrade

Core SDK Update

Install and activate the latest version of the Nillion SDK with nilup:

nilup install latest
nilup use latest

Package Updates

Python Client:

• nillion-client - Update to the latest version of the Python Client to access new features including ECDSA signatures and top-up payments.

Migration Steps

1. Install the latest SDK version with nilup
2. Update any CLI output parsing to handle new JSON/YAML formats (see breaking changes below)
3. Upgrade Python client to access new signature and payment features
4. Review top-up payment implementations to leverage the new balance management system in the Python client

⛓️‍💥 Breaking changes

Standardized CLI Output

The Nillion CLI now standardizes all command outputs to YAML by default, with an option for JSON format. This change affects scripts or tools that parse the Nillion CLI output.

What Changed:

• All Nillion CLI commands now output in YAML format by default
• JSON output available with -output-format json flag
• Consistent error handling with structured output
• More predictable output format for scripting

Example CLI Outputs:

List networks (default YAML output):

> nillion networks list
networks:
- devnet
- qa2
- fermion

List networks with JSON output:

> nillion networks list --output-format json
{
  "networks": [
    "devnet",
    "qa2",
    "fermion"
  ]
}

Error output format

> nillion retrieve-values invalid-id
error: failed to invoke operation: NotFound
cause: []

Required Actions for anyone scripting with the Nillion CLI

• Update any scripts that parse CLI output to handle YAML/JSON formats
• Use the -output-format json if you need JSON specifically
• Review error handling in your scripts to handle the new structured error format

🔧 New feature descriptions & resources

ECDSA Signature Support

The Python client now supports threshold ECDSA signatures, allowing you to sign messages using private keys stored securely in Nillion's network. This enables secure signing operations where the private key never leaves Nillion's distributed system.

Key Features:

• Store ECDSA private keys securely in Nillion
• Sign messages using stored keys without exposing them
• Compatible with Ethereum and other ECDSA systems
• Grant specific users compute permission to sign with your keys
• Includes secp256k1 curve support (used by Ethereum)

Benefits:

• Private keys never leave Nillion's secure network
• Grant controlled signing access to other users/systems
• Perfect for secure wallet management
• Compatible with Web3 authentication systems
• No single point of key exposure

Example using signatures

# Hash the message
digest = hashes.Hash(hashes.SHA256())
digest.update(message)
hashed_message = digest.finalize()

# Store the message digest
digest_value = {
    "tecdsa_digest_message": EcdsaDigestMessage(bytearray(hashed_message)),
}

# Set permissions for the digest
permissions = Permissions.defaults_for_user(client.user_id).allow_compute(
    client.user_id, builtin_tecdsa_program_id
)

# Store the digest
digest_id = await client.store_values(
    digest_value, 
    ttl_days=1,  # Short TTL for the digest
    permissions=permissions
).invoke()

# Set up the signing computation
input_bindings = [
    InputPartyBinding(tecdsa_key_party, client.user_id),
    InputPartyBinding(tecdsa_digest_party, client.user_id)
]
output_bindings = [OutputPartyBinding(tecdsa_output_party, [client.user_id])]

# Execute the signing computation
compute_id = await client.compute(
    builtin_tecdsa_program_id,
    input_bindings,
    output_bindings,
    values={},
    value_ids=[store_id, digest_id],
).invoke()

# Get the signature
result = await client.retrieve_compute_results(compute_id).invoke()
signature: EcdsaSignature = result["tecdsa_signature"]

Learn more:

• Nillion Signatures (tECDSA) Docs
• Python Client Reference: Full API documentation for ECDSA operations
• python-examples repo: Sample code including private key storage and signing within examples_and_tutorials/core_concept_single_party_compute/threshold_ecdsa_signature.py
• Nillion Signature Tools: A live app demo for generating key pairs, storing a private key in Nillion, signing a message with Nillion, and verifying the signature

Top-up Payments System

The new top-up payments system introduces client-side balance management, allowing you to pre-fund the Nillion Python Client for multiple operations. Instead of paying for each operation individually, you can now "top up" your client's balance of NIL once and use it for multiple client operations including storing secrets and running compute.

Key Features:

• Automatic payments - your operations use funds from your balance by default
• Check your available funds anytime with client.balance()
• Top up other users' accounts with the target_user parameter
• Funds expire in 30 days - only add what you'll use soon
• Note: The Top-up Payments feature that has only been introduced in the Python Client (not yet in ts-client)

Benefits:

• Pay once, run many operations
• Skip individual payment processing for each operation
• Client handles all the payment logistics
• Faster operations - no more waiting for payment confirmations

Top-up payments example

# Select your Nillion Network
network = Network.from_config("photon")

# Create payments config and set up Nillion wallet with a private key to pay for operations
nilchain_key: str = 'YOUR_NILCHAIN_PRIVATE_KEY'
payer = NilChainPayer(
    network,
    wallet_private_key=NilChainPrivateKey(bytes.fromhex(nilchain_key)),
    gas_limit=10000000,
)

# Instantiate a Nillion Client with the user, network, and payment information
user_key = PrivateKey('YOUR_NILLION_USER_KEY')
client = await VmClient.create(user_key, network, payer)

# "Top up" client by adding funds to pay for future operations
funds_amount = 1000
print(f"💰 Adding some funds to the client balance: {funds_amount} uNIL")
await client.add_funds(funds_amount)

# Check the balance of the user's funds
balance = client.balance()
print(balance) # 1000

# Perform any Nillion operations! Store secrets, store programs, run blind compute

Learn more:

• Python Client Reference: Full API documentation for the Nillion Python Client, including instructions for payment methods
• python-examples repo: Sample code demonstrating how to use top-up payments in your applications

CLI Permissions Management with update-permissions

The new update-permissions command lets you manage access permissions for stored secrets from the command line. Update who can retrieve, compute on, or delete your secrets.

update-permissions usage

nillion update-permissions --values-id <VALUES_ID> [OPTIONS]

Features:

• Grant/revoke retrieve, update, and delete permissions
• Set compute permissions for specific programs
• Use YAML/JSON files for permission updates
• Update multiple users at once

For all options, run nillion update-permissions --help