tresori_sdk 1.0.0

A comprehensive interface for blockchain wallet management, supporting Self-Custodial, Custodial, and MPC wallet operations.

TreSori SDK

Overview

The TreSori SDK provides a unified, high-level API for blockchain wallet operations. It supports three distinct wallet types to accommodate various security models and use cases:

• Self-Custodial: Full user control with local key management
• Custodial: Service-managed wallets linked to user accounts
• MPC: Enhanced security through distributed key shards with verification flows

Table of Contents

• Features
• Installation
• Quick Start
• API Reference
  • Initialization
  • Self-Custodial Wallet
  • Custodial Wallet
  • MPC Wallet
  • Wallet Balance
• Chain Management
• Error Handling
• Response Formats
• Example App

---

Features

Self-Custodial Wallets

Feature	Description
Mnemonic Generation	Generate BIP39-compliant mnemonic phrases (12/15/18/21/24 words)
Wallet Creation	Create wallets from mnemonic with blockchain registration
Mnemonic Import	Restore wallets from existing mnemonic phrases
Private Key Import	Import wallets directly from private keys
Token Transfers	Transfer native tokens (ETH, MATIC, etc.)
Smart Contract Interaction	Sign and send contract transactions

Custodial Wallets

Feature	Description
Managed Wallet Creation	Create server-managed wallets linked to user IDs
Token Transfers	Transfer native and ERC-20 tokens
Smart Contract Transactions	Execute contract write operations

MPC Wallets

Feature	Description
Email Verification	OTP-based email verification flow
Phone Verification	SMS OTP verification with country code support
Secure Token Transfers	Transfer tokens using distributed key shards
Smart Contract Transactions	Execute contract operations with MPC signing

Multi-Chain Support

• Dynamic chain configuration loaded at runtime
• Support for multiple EVM-compatible networks
• Chain-specific parameters (chain ID, explorer URL, currency)

---

Installation

Add the SDK to your pubspec.yaml:

dependencies:
  tresori_sdk: ^1.0.0

Then run:

flutter pub get

---

Quick Start

import 'package:tresori_sdk/tresori.dart';

void main() async {
  // 1. Initialize the SDK with your API key
  await TreSori().initialize('YOUR_API_KEY');
  
  // 2. Generate a mnemonic phrase
  final mnemonic = TreSori().generateMnemonic();
  print('Mnemonic: $mnemonic');
  
  // 3. Create a wallet
  final wallet = await TreSori().createWallet(
    chain: chain.all.first,  // Use first available chain
    mnemonic: mnemonic,
    userId: 'user_123',
  );
  
  print('Address: ${wallet['address']}');
  print('Private Key: ${wallet['privateKey']}');
}

---

API Reference

Initialization

initialize(String apiKey)

Initializes the SDK with your API key. Must be called before any other operations.

await TreSori().initialize('YOUR_API_KEY');

Parameter	Type	Required	Description
apiKey	String	✅	Your TreSori API key

Throws: Exception if the API key is empty.

---

Self-Custodial Wallet

generateMnemonic({int wordCount = 12})

Generates a BIP39-compliant mnemonic phrase.

// Generate 12-word mnemonic (default)
final mnemonic12 = TreSori().generateMnemonic();

// Generate 24-word mnemonic
final mnemonic24 = TreSori().generateMnemonic(wordCount: 24);

Parameter	Type	Default	Description
wordCount	int	12	Number of words (12, 15, 18, 21, or 24)

Returns: String - Space-separated mnemonic phrase

---

createWallet({required Chain chain, required String mnemonic, required String userId})

Creates a new wallet and registers it with the backend.

final result = await TreSori().createWallet(
  chain: selectedChain,
  mnemonic: 'word1 word2 word3 ... word12',
  userId: 'unique_user_id',
);

print('Address: ${result['address']}');
print('Private Key: ${result['privateKey']}');
print('Mnemonic: ${result['mnemonic']}');

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
mnemonic	String	✅	BIP39 mnemonic phrase
userId	String	✅	Unique user identifier

Returns: Map<String, dynamic>

{
  'mnemonic': String,    // The mnemonic phrase
  'privateKey': String,  // Hex-encoded private key
  'address': String,     // Public wallet address
  'userId': String,      // Associated user ID
}

---

importWalletFromMnemonic(String mnemonic)

Imports an existing wallet from a mnemonic phrase.

final result = TreSori().importWalletFromMnemonic(
  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
);

print('Address: ${result['address']}');
print('Private Key: ${result['privateKey']}');

Parameter	Type	Required	Description
mnemonic	String	✅	Valid BIP39 mnemonic phrase

Returns: Map<String, dynamic>

{
  'privateKey': String,  // Hex-encoded private key
  'address': String,     // Public wallet address
}

---

importWalletFromPrivateKey(String privateKey)

Imports a wallet from a private key.

final result = TreSori().importWalletFromPrivateKey(
  '0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318'
);

print('Address: ${result['address']}');

Parameter	Type	Required	Description
privateKey	String	✅	Hex-encoded private key (with or without 0x prefix)

Returns: Map<String, dynamic>

{
  'privateKey': String,  // Hex-encoded private key
  'address': String,     // Public wallet address
}

---

transferTokens({...})

Transfers native tokens (ETH, MATIC, etc.) to a recipient address.

final txHash = await TreSori().transferTokens(
  chain: selectedChain,
  privateKey: '0x...',
  toAddress: '0xRecipientAddress',
  amount: EtherAmount.fromInt(EtherUnit.ether, 1),  // 1 ETH
  rpcUrl: 'https://rpc.example.com',
);

print('Transaction Hash: $txHash');

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
privateKey	String	✅	Sender's private key
toAddress	String	✅	Recipient's wallet address
amount	EtherAmount	✅	Amount to transfer
rpcUrl	String	✅	RPC endpoint URL

Returns: dynamic - Transaction hash

---

signContractTransaction({...})

Signs and sends a smart contract transaction.

final txHash = await TreSori().signContractTransaction(
  chain: selectedChain,
  privateKey: '0x...',
  transaction: Transaction.callContract(
    contract: deployedContract,
    function: contractFunction,
    parameters: [param1, param2],
  ),
  rpcUrl: 'https://rpc.example.com',
);

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
privateKey	String	✅	Sender's private key
transaction	Transaction	✅	web3dart Transaction object
rpcUrl	String	✅	RPC endpoint URL

Returns: dynamic - Transaction hash

---

Custodial Wallet

createCustodialWallet({required Chain chain, required String userId})

Creates a service-managed custodial wallet.

final result = await TreSori().createCustodialWallet(
  chain: selectedChain,
  userId: 'unique_user_id',
);

print('Custodial Address: ${result['address']}');

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
userId	String	✅	Unique user identifier

Returns: Map<String, dynamic> - Wallet details including address

---

transferCustodialTokens({...})

Transfers tokens from a custodial wallet.

final result = await TreSori().transferCustodialTokens(
  fromAddress: '0xCustodialWalletAddress',
  toAddress: '0xRecipientAddress',
  amount: '1000000000000000000',  // 1 token in wei
  chain: selectedChain,
  tokenAddress: '0xTokenContractAddress',  // Optional: for ERC-20 tokens
);

Parameter	Type	Required	Description
fromAddress	String	✅	Custodial wallet address
toAddress	String	✅	Recipient address
amount	String	✅	Amount in wei (as string)
chain	Chain	✅	Target blockchain network
tokenAddress	String	❌	ERC-20 token contract address (empty for native)

Returns: Map<String, dynamic> - Transaction response

---

writeCustodialSmartContractTransaction({...})

Executes a smart contract write operation from a custodial wallet.

final result = await TreSori().writeCustodialSmartContractTransaction(
  contractAddress: '0xContractAddress',
  functionName: 'transfer',
  parameters: ['0xRecipient', BigInt.from(1000)],
  contractAbi: jsonDecode(abiString),
  fromAddress: '0xCustodialWalletAddress',
  chain: selectedChain,
);

Parameter	Type	Required	Description
contractAddress	String	✅	Deployed contract address
functionName	String	✅	Contract function to call
parameters	List<dynamic>	✅	Function parameters
contractAbi	List<dynamic>	✅	Contract ABI as list
fromAddress	String	✅	Custodial wallet address
chain	Chain	✅	Target blockchain network

Returns: Map<String, dynamic> - Transaction response

---

MPC Wallet

Email Verification

sendEmailVerificationRequest({...})

Sends an OTP verification email.

final result = await TreSori().sendEmailVerificationRequest(
  chain: selectedChain,
  email: '[e-mail]',
  userId: 'unique_user_id',
  isNewUser: true,
);

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
email	String	✅	User's email address
userId	String	✅	Unique user identifier
isNewUser	bool	✅	Whether this is a new user registration

Returns: Map<String, dynamic> - Response indicating OTP was sent

---

verifyEmail({...})

Verifies the email using the OTP received.

final result = await TreSori().verifyEmail(
  chain: selectedChain,
  email: '[e-mail]',
  userId: 'unique_user_id',
  otp: '123456',
  isNewUser: true,
);

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
email	String	✅	User's email address
userId	String	✅	Unique user identifier
otp	String	✅	OTP code from email
isNewUser	bool	✅	Whether this is a new user registration

Returns: Map<String, dynamic> - Verification result with wallet details

---

Phone Verification

sendPhoneVerificationCode({...})

Sends an OTP verification code via SMS.

final result = await TreSori().sendPhoneVerificationCode(
  chain: selectedChain,
  countryCode: '+1',
  phone: '5551234567',
  userId: 'unique_user_id',
  isNewUser: true,
);

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
countryCode	String	✅	Country code (e.g., '+1', '+44')
phone	String	✅	Phone number without country code
userId	String	✅	Unique user identifier
isNewUser	bool	✅	Whether this is a new user registration

Returns: Map<String, dynamic> - Response indicating OTP was sent

---

verifyPhone({...})

Verifies the phone number using the OTP received.

final result = await TreSori().verifyPhone(
  chain: selectedChain,
  countryCode: '+1',
  phone: '5551234567',
  userId: 'unique_user_id',
  otp: '123456',
  isNewUser: true,
);

Parameter	Type	Required	Description
chain	Chain	✅	Target blockchain network
countryCode	String	✅	Country code
phone	String	✅	Phone number
userId	String	✅	Unique user identifier
otp	String	✅	OTP code from SMS
isNewUser	bool	✅	Whether this is a new user registration

Returns: Map<String, dynamic> - Verification result with wallet details

---

MPC Token Transfers

transferMpcTokens({...})

Transfers tokens using MPC signing.

final result = await TreSori().transferMpcTokens(
  fromAddress: '0xMpcWalletAddress',
  toAddress: '0xRecipientAddress',
  amount: '1000000000000000000',
  chain: selectedChain,
  userShards: 'encrypted_user_shard_data',
  userIdentity: 'user_identity_token',
  tokenAddress: '',  // Empty for native token
);

Parameter	Type	Required	Description
fromAddress	String	✅	MPC wallet address
toAddress	String	✅	Recipient address
amount	String	✅	Amount in wei
chain	Chain	✅	Target blockchain network
userShards	String	✅	User's encrypted key shards
userIdentity	String	✅	User's identity token
tokenAddress	String	❌	ERC-20 token address (empty for native)

Returns: Map<String, dynamic> - Transaction response

---

writeMpcSmartContractTransaction({...})

Executes a smart contract write operation using MPC signing.

final result = await TreSori().writeMpcSmartContractTransaction(
  contractAddress: '0xContractAddress',
  functionName: 'mint',
  parameters: [BigInt.from(100)],
  contractAbi: jsonDecode(abiString),
  fromAddress: '0xMpcWalletAddress',
  chain: selectedChain,
  userShards: 'encrypted_user_shard_data',
  userIdentity: 'user_identity_token',
);

Parameter	Type	Required	Description
contractAddress	String	✅	Contract address
functionName	String	✅	Function to call
parameters	List<dynamic>	✅	Function parameters
contractAbi	List<dynamic>	✅	Contract ABI
fromAddress	String	✅	MPC wallet address
chain	Chain	✅	Target blockchain network
userShards	String	✅	User's encrypted key shards
userIdentity	String	✅	User's identity token

Returns: Map<String, dynamic> - Transaction response

---

Wallet Balance

getWalletBalance({required String address, required Chain chain})

Retrieves the balance of a wallet.

final result = await TreSori().getWalletBalance(
  address: '0xWalletAddress',
  chain: selectedChain,
);

print('Balance: ${result['balance']}');

Parameter	Type	Required	Description
address	String	✅	Wallet address to query
chain	Chain	✅	Target blockchain network

Returns: Map<String, dynamic> - Balance information

---

Chain Management

After initialization, available chains are accessible via the global chain object:

import 'package:tresori_sdk/tresori.dart';

// Initialize first
await TreSori().initialize('YOUR_API_KEY');

// Access all available chains
final allChains = chain.all;

// Iterate through chains
for (final c in chain.all) {
  print('${c.blockchain} - ${c.network}');
  print('  Chain ID: ${c.chainId}');
  print('  Currency: ${c.currency}');
  print('  Explorer: ${c.explorerUrl}');
}

Chain Model

class Chain {
  final int id;           // Internal ID
  final String blockchain;  // e.g., "Ethereum", "Polygon"
  final String network;     // e.g., "Mainnet", "Amoy"
  final String chainId;     // e.g., "1", "80002"
  final String explorerUrl; // Block explorer URL
  final String currency;    // e.g., "ETH", "MATIC"
  final String logo;        // Logo URL
  final String createdAt;   // Creation timestamp
}

---

Error Handling

The SDK throws exceptions for error conditions. Always wrap calls in try-catch blocks:

try {
  await TreSori().initialize('YOUR_API_KEY');
  
  final wallet = await TreSori().createWallet(
    chain: selectedChain,
    mnemonic: mnemonic,
    userId: userId,
  );
} on Exception catch (e) {
  print('Error: $e');
  // Handle specific error cases
}

Common Exceptions

Exception	Cause
Wallet not initialized. Call initialize() first.	SDK methods called before initialize()
API key is required. Call initialize() first.	Empty API key provided
Network exceptions	API connectivity issues

---

Response Formats

Successful Wallet Creation

{
  'mnemonic': 'word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12',
  'privateKey': '0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318',
  'address': '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE56',
  'userId': 'user_123',
}

Wallet Import (Mnemonic/Private Key)

{
  'privateKey': '0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318',
  'address': '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE56',
}

---

Example App

A complete example application is included in the /example directory demonstrating:

• SDK initialization
• Self-custodial wallet operations
• Custodial wallet management
• MPC verification flows
• Token transfers
• Smart contract interactions

To run the example:

cd example
flutter pub get
flutter run

---

Exports

The SDK re-exports commonly used packages for convenience:

import 'package:tresori_sdk/tresori.dart';

// Includes:
// - TreSori (main SDK class)
// - Chain (blockchain model)
// - chain (global chain list accessor)
// - ChainList (chain list manager)
// - Transaction, EtherAmount, EtherUnit (from web3dart)
// - Wallet utilities (from wallet package)

---

License

See LICENSE for details.

---

Support

For issues, feature requests, or questions, please contact the TreSori team.