Falcon-Algorand SDK

Create and manage post-quantum secure Algorand accounts using Falcon signatures

A TypeScript SDK for integrating Falcon post-quantum signatures with Algorand blockchain accounts. Create quantum-resistant accounts, convert existing accounts, and sign transactions using the Falcon signature scheme through Algorand's LogicSig system. Builds emit ESM + type declarations to dist/ (run npm run build).

🚀 Features

• 🔐 Account Creation: Generate new Falcon-protected Algorand accounts
• 🔄 Account Conversion: Convert existing accounts to Falcon-protected via rekeying
• 📝 Transaction Signing: Sign transactions with Falcon post-quantum signatures
• 📦 Transaction Groups: Support for atomic transaction groups
• 🌐 Multi-Network: MainNet, TestNet, and BetaNet support
• 💾 Account Management: Backup, restore, and key rotation
• 🛠️ Developer Tools: Comprehensive utilities and fee estimation

Prerequisites

• Node.js 18 or higher
• Basic understanding of Algorand blockchain
• Access to Algorand network (TestNet for development)

📦 Installation

npm install falcon-algo-sdk

Dependencies

The SDK requires:

• algosdk ^3.5.2 - Algorand JavaScript SDK
• falcon-signatures 1.4.0 - Falcon post-quantum signature library
  • 📦 NPM Package
  • 📁 GitHub Repository
  • 🌐 Live Demo

🏁 Quick Start

import FalconAlgoSDK, { Networks } from 'falcon-algo-sdk';

async function quickStart() {
  // Initialize SDK
  const sdk = new FalconAlgoSDK(Networks.TESTNET);
  
  // Create new Falcon-protected account
  const account = await sdk.createFalconAccount();
  console.log(`New account: ${account.address}`);
  
  // Create and sign a payment
  const payment = await sdk.createPayment({
    sender: account.address,
    receiver: 'RECEIVER_ADDRESS_HERE',
    amount: 1000000, // 1 Algo in microAlgos
    note: 'Post-quantum payment'
  }, account);
  
  console.log('Transaction signed with Falcon signature!');
}

quickStart();

📖 API Reference

Class: FalconAlgoSDK

Constructor

new FalconAlgoSDK(network?, customAlgod?)

• network - Network configuration (default: Networks.TESTNET)
• customAlgod - Custom Algod client (optional)

Core Methods

createFalconAccount(options?)

Creates a new Falcon-protected Algorand account.

const account = await sdk.createFalconAccount({
  generateEdKeys: true // Generate backup ed25519 keys
});

Returns: Account information object with Falcon keys and LogicSig details.

convertToFalconAccount(account, falconKeys?)

Converts an existing Algorand account to Falcon-protected.

const conversionInfo = await sdk.convertToFalconAccount(
  'mnemonic phrase here', // or account object
  falconKeys // optional existing Falcon keys
);

// Submit the conversion
const result = await sdk.submitConversion(conversionInfo);

Returns: Conversion information with rekey transaction ready for submission.

createPayment(params, accountInfo)

Creates and signs a payment transaction.

const signedTxn = await sdk.createPayment({
  sender: 'SENDER_ADDRESS',
  receiver: 'RECEIVER_ADDRESS',
  amount: 1000000,
  note: 'Payment note'
}, accountInfo);

signTransaction(transaction, accountInfo)

Signs any Algorand transaction with Falcon signature.

const signedTxn = await sdk.signTransaction(txnObject, accountInfo, txnObject.txID());

Account Management

getAccountInfo(address)

hasSufficientBalance(address, amount)

createLogicSig(accountInfo, txId)

Advanced Features

rotateFalconKeys(currentAccountInfo, oldFalconKeys)

Rotates Falcon keys for enhanced security.

signTransactionGroup(transactions, accountInfos)

Signs multiple transactions as an atomic group.

submitTransactionGroup(signedTransactions, maxRounds?)

Submits and confirms transaction groups.

estimateFees(transactionCount?)

Estimates fees including Falcon signature overhead.

backupAccount(accountInfo, includeSecretKey?)

restoreAccount(backupJson, secretKey?)

Backup and restore account information.

Utility Functions

import { FalconAlgoUtils } from 'falcon-algo-sdk';

// Convert between Algos and microAlgos
const microAlgos = FalconAlgoUtils.algosToMicroAlgos(1.5);
const algos = FalconAlgoUtils.microAlgosToAlgos(1500000);

// Validate account structure
const isValid = FalconAlgoUtils.validateAccountInfo(accountInfo);

// Generate random lease
const lease = FalconAlgoUtils.generateRandomLease();

Network Configurations

import { Networks } from 'falcon-algo-sdk';

// Available networks
Networks.MAINNET  // Algorand MainNet
Networks.TESTNET  // Algorand TestNet  
Networks.BETANET  // Algorand BetaNet

💡 Usage Examples

Creating a New Falcon Account

import FalconAlgoSDK, { Networks } from 'falcon-algo-sdk';

const sdk = new FalconAlgoSDK(Networks.TESTNET);

// Create account
const account = await sdk.createFalconAccount();

// Account structure:
// {
//   address: 'ALGORAND_ADDRESS',
//   falconKeys: {
//     publicKey: 'hex_public_key',
//     secretKey: 'hex_secret_key'
//   },
//   backupAccount: {
//     address: 'backup_address',
//     mnemonic: '25 word mnemonic'
//   },
//   logicSig: {
//     program: 'base64_teal_program',
//     signature: 'hex_falcon_signature'
//   },
//   type: 'falcon-protected'
// }

Converting Existing Account

// Convert existing account
const mnemonic = 'your 25 word mnemonic here...';
const conversionInfo = await sdk.convertToFalconAccount(mnemonic);

// Submit rekey transaction
const result = await sdk.submitConversion(conversionInfo);
console.log(`Account converted! TxID: ${result.txId}`);

Making Payments

// Create payment transaction
const payment = await sdk.createPayment({
  sender: account.address,
  receiver: 'RECEIVER_ADDRESS',
  amount: 1000000, // 1 Algo
  note: 'Falcon-secured payment'
}, account);

// Submit to network
const result = await sdk.algod.sendRawTransaction(payment.blob).do();

Transaction Groups

// Create multiple transactions
const txn1 = /* payment transaction */;
const txn2 = /* asset transfer */;

// Sign as group
const signedGroup = await sdk.signTransactionGroup(
  [txn1, txn2], 
  [account1, account2]
);

// Submit group
const result = await sdk.submitTransactionGroup(signedGroup);

🧪 Testing

Basic Tests

Run the unit test suite (no network required):

npm run build
npm test

This runs 10 comprehensive tests covering:

• SDK initialization and configuration
• Account creation and conversion
• Transaction signing and LogicSig creation
• Backup/restore functionality
• Utility functions

Integration Test

Important: The integration test requires TestNet funding.

npm run test:integration

The integration test demonstrates the complete workflow:

1. Account Creation: Creates a new Algorand account with mnemonic
2. Funding Prompt: Provides TestNet faucet instructions
3. Account Conversion: Converts to Falcon-protected via rekeying
4. Transaction Group: Creates payment with dummy transactions for pool optimization
5. Submission: Submits and confirms the post-quantum secured transaction

Integration Test Requirements

• Internet connection for TestNet access
• Manual funding step at https://bank.testnet.algorand.network/
• Approximately 2-3 minutes to complete
• Reuses standard-account.json and falcon-protected-account.json between runs; delete them to regenerate fresh accounts/keys.
• Uses BigInt-safe JSON serialization so you can inspect the saved files directly.
• Builds a transaction group (one real payment + dummy zero-amount txns) to ensure enough pool bytes for the Falcon LogicSig arguments.

Generated Files

The integration test creates these files in the project directory:

• standard-account.json - Original account details
• falcon-protected-account.json - Conversion information

Sample logs of the integration test

🦅 Starting Falcon-Algorand Integration Test...

🚀 Falcon-Algorand SDK Integration Test
=====================================
This test demonstrates the complete flow from standard to post-quantum Resistant Algorand accounts.

[10:32:08] 🔄 Initializing Falcon-Algorand SDK on TestNet...
[10:32:08] ✅ SDK initialized successfully
[10:32:08] 📝 Connected to: https://testnet-api.algonode.cloud
[10:32:08] 📝 Found existing standard account. Reusing saved account (delete standard-account.json to regenerate).
[10:32:08] 🔷 Address: ZXJ4CBDJKILFBEXLNO3F43UQUSA73PWP4KRFWHFVWZTD32NCTES4UCDCOU
[10:32:08] 📝 Account ZXJ4CBDJKI... balance: 0 Algo (0 microAlgos)

🏦 ACCOUNT FUNDING REQUIRED
===========================
Please fund the account with at least 0.2 Algo for testing:
1. Visit: https://bank.testnet.algorand.network/
2. Enter address: ZXJ4CBDJKILFBEXLNO3F43UQUSA73PWP4KRFWHFVWZTD32NCTES4UCDCOU
3. Click "Dispense" to receive 10 TestNet Algos
4. Wait for the transaction to complete

Press Enter after funding the account...
[10:32:32] 🔄 Checking account balance after funding...
[10:32:32] 📝 Account ZXJ4CBDJKI... balance: 10 Algo (10000000 microAlgos)
[10:32:32] ✅ Required: 0.2 Algo - Sufficient funds
[10:32:32] ✅ Account successfully funded!
[10:32:32] 🔄 Converting account to Falcon-protected...
[10:32:32] 🦅 Generating Falcon keypair...
Converting existing Algorand account to Falcon-protected...
Converting account: ZXJ4CBDJKILFBEXLNO3F43UQUSA73PWP4KRFWHFVWZTD32NCTES4UCDCOU
Selected counter: 0
[falcon_wrapper] falcon_det1024_sign_compressed_wrapper called
[falcon_wrapper] Signature generated successfully (1235 bytes)
[falcon_wrapper] falcon_det1024_verify_compressed_wrapper called with:
  - sig: 0x18ae0
  - sig_len: 1235
  - pk: 0x18fb8
  - msg: 0x18ab8
  - msg_len: 32
[falcon_wrapper] Signature verified successfully
✅ Conversion prepared. Original: ZXJ4CBDJKILFBEXLNO3F43UQUSA73PWP4KRFWHFVWZTD32NCTES4UCDCOU, New: Z54XNYOBI56O6KX7NMVSSW5DE5Y5764ME3AVS2ENHEIIA3N7DQ6UDAJB3Q
Submit the rekey transaction to complete conversion: INSAVMDTS3S2KX4WZ7YY434EFITOT76RMIU7IHISFKUJBGWDFHIA
[10:32:32] ✅ Falcon keypair generated successfully!
[10:32:32] 🦅 Falcon Public Key: 0a472d786081f0003f2d41825c075a2ca04feb7f...
[10:32:32] 🔷 Original Address: ZXJ4CBDJKILFBEXLNO3F43UQUSA73PWP4KRFWHFVWZTD32NCTES4UCDCOU
[10:32:32] 🔐 New PQ Address: Z54XNYOBI56O6KX7NMVSSW5DE5Y5764ME3AVS2ENHEIIA3N7DQ6UDAJB3Q
[10:32:32] 📝 LogicSig Program: DCYBAQAxFy2AgQ4KRy14YIHwAD8tQYJcB1osoE/r... (2408 chars)
[10:32:32] 📝 Falcon account info saved to: falcon-protected-account.json
[10:32:32] 🔄 Submitting rekey transaction to convert account to post-quantum security...
Submitting rekey transaction...
Rekey transaction submitted: INSAVMDTS3S2KX4WZ7YY434EFITOT76RMIU7IHISFKUJBGWDFHIA
Waiting for confirmation...
✅ Rekey confirmed in round: 58444644
[10:32:36] ✅ Rekey transaction submitted successfully!
[10:32:36] 🔷 Transaction ID: INSAVMDTS3S2KX4WZ7YY434EFITOT76RMIU7IHISFKUJBGWDFHIA
[10:32:36] 📝 Confirmed in round: 58444644
[10:32:36] 🔐 Account is now protected by Falcon post-quantum signatures!
[10:32:36] 🔄 Verifying account rekey status...
[10:32:36] 📝 Rekeyed Account: 
[10:32:36] 📝 Auth Address: Z54XNYOBI56O6KX7NMVSSW5DE5Y5764ME3AVS2ENHEIIA3N7DQ6UDAJB3Q
[10:32:36] 📝 New Address: Z54XNYOBI56O6KX7NMVSSW5DE5Y5764ME3AVS2ENHEIIA3N7DQ6UDAJB3Q
[10:32:36] ✅ ✅ Account successfully rekeyed to Falcon LogicSig!
[10:32:36] 🔐 Auth Address: Z54XNYOBI56O6KX7NMVSSW5DE5Y5764ME3AVS2ENHEIIA3N7DQ6UDAJB3Q
[10:32:36] 🔄 Creating post-quantum Resistant account payment transaction group...
[10:32:36] 🔷 Sending 0.1 Algo to: UTI7PAASILRDA3ISHY5M7J7LNRX2AIVQJWI7ZKCCGKVLMFD3VPR5PWSZ4I
[10:32:36] 📝 Network fee: 0 microAlgos per transaction
[10:32:36] 📝 Transaction validity: rounds 58444644 to 58445644
[10:32:36] 🔄 Creating dummy LogicSig for transaction group optimization...
[10:32:36] 📝 Dummy LogicSig Address: MK4BJ4NAVYMCPBFDW2MVUF66MG6ADZBSESKGTC6HMEZGT7VQSFYDOJ27ZI
[10:32:36] ✅ Transaction group created with additional pool bytes
[10:32:36] 📝 Group contains 4 transactions
[10:32:36] 🔷 Main payment: 0.1 Algo from ZXJ4CBDJKILFBEXLNO3F43UQUSA73PWP4KRFWHFVWZTD32NCTES4UCDCOU to UTI7PAASILRDA3ISHY5M7J7LNRX2AIVQJWI7ZKCCGKVLMFD3VPR5PWSZ4I
[10:32:36] 📝 Dummy transactions: 3x zero-amount transactions for pool byte optimization
[10:32:36] 📝 Total group fee: 4000 microAlgos (covered by main transaction)
[10:32:36] 🔄 Creating LogicSig for transaction signing...
[falcon_wrapper] falcon_det1024_sign_compressed_wrapper called
[falcon_wrapper] Signature generated successfully (1236 bytes)
[10:32:36] ✅ LogicSig created with address: Z54XNYOBI56O6KX7NMVSSW5DE5Y5764ME3AVS2ENHEIIA3N7DQ6UDAJB3Q
[10:32:36] 📝 LogicSig arguments: 1 (Falcon signature included)
[10:32:36] 🦅 Falcon signature size: 1236 bytes
[10:32:36] 🦅 Signing transaction group with Falcon post-quantum signature...
[10:32:36] ✅ Transaction group signed successfully with Falcon signature!
[10:32:36] 🦅 Main transaction signed with Falcon signature (1236 bytes)
[10:32:36] 📝 Dummy transactions signed with optimization LogicSig
[10:32:36] 📝 Total group size: 4194 bytes
[10:32:36] 🔄 Submitting transaction group to TestNet...
[10:32:36] ✅ Transaction group submitted successfully!
[10:32:36] 🔷 Group Transaction ID: GS2O7I5RFGKX7J34GUQCU76GHCYWCWNFYDQARGUF5O77ARJENINA
[10:32:36] 🔄 Waiting for transaction confirmation: GS2O7I5RFGKX7J34GUQCU76GHCYWCWNFYDQARGUF5O77ARJENINA
[10:32:41] 📝 Waiting... (round 1/10)
[10:32:42] ✅ 🎉 POST-QUANTUM PAYMENT CONFIRMED!
[10:32:42] ✅ Confirmed in round: undefined
[10:32:42] 📝 Transaction fee: 4000 microAlgos
[10:32:42] 🔄 Verifying final balances...
[10:32:42] 📝 Account ZXJ4CBDJKI... balance: 9.895 Algo (9895000 microAlgos)
[10:32:42] 📝 Account UTI7PAASIL... balance: 63.350318 Algo (63350318 microAlgos)

🎯 TRANSACTION SUMMARY
=====================
✅ Successfully sent 0.1 Algo using Falcon post-quantum signatures!
📄 Transaction ID: GS2O7I5RFGKX7J34GUQCU76GHCYWCWNFYDQARGUF5O77ARJENINA
🌐 View on LORA: https://lora.algokit.io/testnet/transaction/GS2O7I5RFGKX7J34GUQCU76GHCYWCWNFYDQARGUF5O77ARJENINA
🔐 Signature Algorithm: Falcon-1024 (Post-Quantum Resistant)
📊 Signature Size: 1236 bytes
💰 Transaction Fee: 4000 microAlgos
🏦 Sender Final Balance: 9.895 Algo
🎯 Receiver Balance: 63.350318 Algo

🔬 EDUCATIONAL INSIGHTS
=======================
🛡️  Post-Quantum Security: This transaction is resistant against quantum computer attacks
🔑 Falcon Signatures: Used deterministic lattice-based cryptography
📋 LogicSig Integration: Leveraged Algorand's smart contract system for verification
🔄 Account Rekeying: Original account now requires Falcon signatures for all transactions
🌐 Blockchain Compatibility: Full integration with Algorand's consensus mechanism
⚡ Performance: Near-native performance thanks to WebAssembly implementation

📁 FILES CREATED
================
📄 standard-account.json - Original Algorand account details
📄 falcon-protected-account.json - Complete Falcon account information
💡 These files contain all necessary information for account recovery and future use
[10:32:42] ✅ 🎉 Integration test completed successfully!
[10:32:42] 🔐 Your Algorand account is now protected by post-quantum cryptography!

Example Usage

Run the basic example:

npm run example

CLI

Install globally (or use npx):

npm install -g falcon-algo-sdk

Usage:

# Create a new Falcon-protected account (saves JSON to cwd)
# Create a new Falcon-protected account (saves JSON to cwd)
falcon-algo create --network testnet

# Convert an existing mnemonic-based account (prompts if omitted)
falcon-algo convert --network testnet --mnemonic "word list ..."

Networks: mainnet, testnet (default), betanet.

The CLI saves generated or converted account details as JSON in the current directory (BigInt-safe), including addresses, Falcon keys, and rekey transaction info.

🏗️ How It Works

The Falcon-Algorand SDK uses Algorand's LogicSig (Logic Signature) functionality to embed Falcon post-quantum signatures into the blockchain:

1. TEAL Program Generation: Creates a TEAL smart contract that verifies Falcon signatures
2. Account Creation: Generates LogicSig accounts with embedded Falcon public keys
3. Transaction Signing: Signs transactions with Falcon signatures passed as LogicSig arguments
4. On-Chain Verification: Algorand nodes verify Falcon signatures using the embedded TEAL program
5. Address Safety: TEAL compilation iterates a counter (0–255) to pick a LogicSig address that is off the ed25519 curve (avoids ECDSA ownership collisions); the chosen counter is stored in logicSig.counter.
6. TxID Binding: LogicSig args are a Falcon signature over the transaction ID, binding the LogicSig proof to the specific transaction.

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Application   │───▶│  Falcon-Algo-SDK │───▶│   Algorand      │
│                 │    │                  │    │   Network       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │ Falcon Signatures│
                       │    (WASM)        │
                       └──────────────────┘

Security Model

• Post-Quantum Resistance: Falcon signatures remain secure against quantum attacks
• Deterministic Signing: Same message produces same signature for auditability
• LogicSig Integration: Leverages Algorand's native smart contract verification
• Key Management: Secure key generation using libsodium's ChaCha20 CSPRNG

🔒 Security Considerations

Best Practices

• 🔐 Secure Key Storage: Store Falcon secret keys securely and never share them
• 🧪 Test First: Always test on TestNet before using MainNet
• 💾 Backup Keys: Create secure backups of your Falcon keys
• 🔄 Key Rotation: Regularly rotate Falcon keys for enhanced security
• 📊 Monitor Transactions: Verify all transactions before submission

Limitations

• Signature Size: Falcon signatures are larger (~1,230 bytes) than ed25519 signatures
• Transaction Fees: LogicSig transactions have slightly higher fees
• Network Support: Requires Algorand network to support falcon_verify opcode
• Key Recovery: No mnemonic recovery for Falcon keys (backup required)

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• 🐛 Issues: GitHub Issues
• 📚 Documentation: This README and inline code documentation
• 💬 Community: Join the discussion in repository issues

⚠️ Important: This is experimental software. While Falcon signatures are cryptographically secure, this implementation should be thoroughly tested before production use. Post-quantum cryptography is an evolving field - stay updated with the latest developments.