QuickSign (KIP-0015)

QuickSign is a Kadena Improvement Proposal (KIP-0015) that enables batch transaction signing in eckoWALLET. Instead of signing transactions one at a time, users can review and sign multiple transactions together, dramatically improving UX for complex DeFi operations.

Overview

QuickSign extends the Kadena signing API with a new endpoint that allows wallets to present multiple transactions to users for batch approval.

Official Specification: KIP-0015 on GitHub

Benefits

• ⚡ Faster UX - Sign multiple transactions at once

• 🔄 Atomic Operations - All or nothing approach for complex workflows

• 💰 DeFi Optimized - Perfect for multi-step swaps, liquidity operations

• 🎯 Better Context - Users see the full operation, not isolated steps

Use Cases

QuickSign is ideal for:

• Multi-hop swaps - Token A → Token B → Token C

• Liquidity operations - Add liquidity + stake LP tokens

• Cross-chain transfers - Multiple signatures required

• Batch operations - Process multiple similar transactions

• Complex DeFi - Any operation requiring multiple signatures

How QuickSign Works

Traditional Signing Flow

Without QuickSign:

1. dApp requests signature for transaction 1

2. User approves

3. dApp requests signature for transaction 2

4. User approves

5. dApp requests signature for transaction 3

6. User approves

7. ... (repeat for each transaction)

Problems:

• User must approve each transaction individually

• Poor UX for multi-step operations

• No context about the overall operation

• Risk of partial completion if user cancels mid-flow

QuickSign Flow

With QuickSign:

1. dApp requests signatures for ALL transactions at once

2. User sees complete operation

3. User approves all signatures in one action

4. All transactions are signed together

Advantages:

• Single approval for entire operation

• User sees full context

• Faster and more efficient

• Clear all-or-nothing semantics

API Reference

Method: kda_requestQuickSign

Request batch signing of multiple Kadena transactions.

Request Format

window.kadena.request({
  method: 'kda_requestQuickSign',
  data: {
    networkId: string,           // 'mainnet01', 'testnet04', 'development'
    commandSigDatas: Array<CommandSigData>
  }
})

Parameters

networkId (string, required)

• The Kadena network to use

• Valid values: 'mainnet01', 'testnet04', 'development'

commandSigDatas (Array, required)

• Array of CommandSigData objects

• Each represents one transaction to sign

• Minimum: 1 transaction

• Maximum: Determined by wallet (eckoWALLET supports up to 100)

CommandSigData Structure

Each CommandSigData object contains:

interface CommandSigData {
  cmd: string;              // JSON-stringified Pact command
  sigs: Array<Signer>;      // Array of signers
}

cmd (string, required)

• JSON-stringified Pact command object

• Must follow Chainweb command format

• See Chainweb Pact API

sigs (Array, required)

• Array of signer objects

• Each signer represents a public key that should sign

• Use null for signatures you're requesting

Signer Structure

interface Signer {
  pubKey: string;           // Public key (lowercase base-16)
  sig?: string | null;      // Signature or null to request
}

pubKey (string, required)

• Lowercase base-16 encoded public key

• 64 characters hex string

• Example: "5a2afbc631fc209296f5b1b9bfd3956048e3bc40ca3cb62afac329c944be08f5"

sig (string | null, optional)

• If null or omitted: Request signature for this public key

• If string: Pre-existing signature (wallet won't sign)

• Lowercase base-16 encoded signature

Response Format

Success Response

interface QuickSignResponse {
  status: 'success';
  quickSignData: Array<{
    commandSigData: CommandSigData;
    outcome: {
      hash: string;
      result: 'success';
    };
  }>;
}

Response Fields:

• status: 'success' if user approved

• quickSignData: Array of signed commands (one per input)

  • commandSigData: Original command with signatures added

  • outcome.hash: Transaction hash (request key)

  • outcome.result: 'success' if signed successfully

Error Response

interface QuickSignError {
  status: 'fail';
  error: string;
}

Common Errors:

• "QuickSign fail: wallet public key not found" - Wallet doesn't control requested key

• "User rejected the request" - User canceled in wallet UI

• "Invalid command format" - Malformed command

• "Network mismatch" - Wrong network selected in wallet

Complete Example

Basic QuickSign Implementation

// Build your Pact commands
const cmd1 = {
  payload: {
    exec: {
      code: '(coin.transfer "sender" "receiver1" 1.0)',
      data: {}
    }
  },
  signers: [{
    pubKey: 'sender-public-key',
    clist: [
      { name: 'coin.GAS', args: [] },
      { name: 'coin.TRANSFER', args: ['sender', 'receiver1', 1.0] }
    ]
  }],
  meta: {
    chainId: '1',
    sender: 'sender-account',
    gasLimit: 2500,
    gasPrice: 0.000001,
    ttl: 28800,
    creationTime: Math.floor(Date.now() / 1000)
  },
  networkId: 'mainnet01',
  nonce: `quicksign-${Date.now()}-1`
};

const cmd2 = {
  payload: {
    exec: {
      code: '(coin.transfer "sender" "receiver2" 2.0)',
      data: {}
    }
  },
  signers: [{
    pubKey: 'sender-public-key',
    clist: [
      { name: 'coin.GAS', args: [] },
      { name: 'coin.TRANSFER', args: ['sender', 'receiver2', 2.0] }
    ]
  }],
  meta: {
    chainId: '1',
    sender: 'sender-account',
    gasLimit: 2500,
    gasPrice: 0.000001,
    ttl: 28800,
    creationTime: Math.floor(Date.now() / 1000)
  },
  networkId: 'mainnet01',
  nonce: `quicksign-${Date.now()}-2`
};

// Request QuickSign
try {
  const result = await window.kadena.request({
    method: 'kda_requestQuickSign',
    data: {
      networkId: 'mainnet01',
      commandSigDatas: [
        {
          cmd: JSON.stringify(cmd1),
          sigs: [{
            pubKey: 'sender-public-key',
            sig: null  // Request signature
          }]
        },
        {
          cmd: JSON.stringify(cmd2),
          sigs: [{
            pubKey: 'sender-public-key',
            sig: null  // Request signature
          }]
        }
      ]
    }
  });

  if (result.status === 'success') {
    console.log('All transactions signed!');

    // Send each signed transaction to blockchain
    for (const signedTx of result.quickSignData) {
      const response = await fetch(`${networkUrl}/api/v1/send`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          cmds: [signedTx.commandSigData]
        })
      });

      const data = await response.json();
      console.log('Transaction sent:', data.requestKeys[0]);
    }
  }
} catch (error) {
  console.error('QuickSign failed:', error);
}

Multi-Step DeFi Operation

Example: Swap Token A → B, then stake Token B

const performSwapAndStake = async (
  userAccount,
  userPubKey,
  amountA,
  minAmountB
) => {
  const creationTime = Math.floor(Date.now() / 1000);

  // Command 1: Swap A for B
  const swapCmd = {
    payload: {
      exec: {
        code: `(dex.swap-exact-in
          "${userAccount}"
          "token-a"
          "token-b"
          ${amountA}
          ${minAmountB}
        )`,
        data: {}
      }
    },
    signers: [{
      pubKey: userPubKey,
      clist: [
        { name: 'coin.GAS', args: [] },
        {
          name: 'token-a.TRANSFER',
          args: [userAccount, 'dex-contract', amountA]
        }
      ]
    }],
    meta: {
      chainId: '1',
      sender: userAccount,
      gasLimit: 5000,
      gasPrice: 0.000001,
      ttl: 28800,
      creationTime
    },
    networkId: 'mainnet01',
    nonce: `swap-stake-${Date.now()}-1`
  };

  // Command 2: Stake received Token B
  const stakeCmd = {
    payload: {
      exec: {
        code: `(staking.stake "${userAccount}" "token-b")`,
        data: {}
      }
    },
    signers: [{
      pubKey: userPubKey,
      clist: [
        { name: 'coin.GAS', args: [] },
        {
          name: 'token-b.TRANSFER',
          args: [userAccount, 'staking-contract', minAmountB]
        }
      ]
    }],
    meta: {
      chainId: '1',
      sender: userAccount,
      gasLimit: 3000,
      gasPrice: 0.000001,
      ttl: 28800,
      creationTime
    },
    networkId: 'mainnet01',
    nonce: `swap-stake-${Date.now()}-2`
  };

  // Execute QuickSign
  const result = await window.kadena.request({
    method: 'kda_requestQuickSign',
    data: {
      networkId: 'mainnet01',
      commandSigDatas: [
        {
          cmd: JSON.stringify(swapCmd),
          sigs: [{ pubKey: userPubKey, sig: null }]
        },
        {
          cmd: JSON.stringify(stakeCmd),
          sigs: [{ pubKey: userPubKey, sig: null }]
        }
      ]
    }
  });

  if (result.status === 'success') {
    // Both transactions signed - send to blockchain
    // Implementation depends on your needs (parallel or sequential)
    return result.quickSignData;
  }

  throw new Error('QuickSign rejected');
};

Advanced Patterns

Multi-Signature Transactions

QuickSign supports transactions requiring multiple signatures:

const multiSigCmd = {
  payload: {
    exec: {
      code: '(treasury.transfer-funds 1000.0)',
      data: {}
    }
  },
  signers: [
    {
      pubKey: 'ceo-public-key',
      clist: [
        { name: 'treasury.TRANSFER', args: [1000.0] }
      ]
    },
    {
      pubKey: 'cfo-public-key',
      clist: [
        { name: 'treasury.TRANSFER', args: [1000.0] }
      ]
    }
  ],
  meta: { /* ... */ },
  networkId: 'mainnet01',
  nonce: 'multisig-tx'
};

// Request signatures for BOTH public keys
const result = await window.kadena.request({
  method: 'kda_requestQuickSign',
  data: {
    networkId: 'mainnet01',
    commandSigDatas: [{
      cmd: JSON.stringify(multiSigCmd),
      sigs: [
        { pubKey: 'ceo-public-key', sig: null },
        { pubKey: 'cfo-public-key', sig: null }
      ]
    }]
  }
});

Note: Wallet will only sign for keys it controls. For multi-sig with different parties, coordinate signing separately.

Partial Signing

Some signatures pre-filled, others requested:

// Already have CEO signature, need CFO
const result = await window.kadena.request({
  method: 'kda_requestQuickSign',
  data: {
    networkId: 'mainnet01',
    commandSigDatas: [{
      cmd: JSON.stringify(multiSigCmd),
      sigs: [
        {
          pubKey: 'ceo-public-key',
          sig: 'pre-existing-ceo-signature-hex'  // Already signed
        },
        {
          pubKey: 'cfo-public-key',
          sig: null  // Request this signature
        }
      ]
    }]
  }
});

Error Handling

Comprehensive error handling:

const quickSignWithRetry = async (commandSigDatas, maxRetries = 2) => {
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const result = await window.kadena.request({
        method: 'kda_requestQuickSign',
        data: {
          networkId: 'mainnet01',
          commandSigDatas
        }
      });

      if (result.status === 'success') {
        return result.quickSignData;
      }

      throw new Error('QuickSign status not success');

    } catch (error) {
      attempt++;

      if (error.message?.includes('User rejected')) {
        // Don't retry on user rejection
        throw new Error('User canceled QuickSign');
      }

      if (error.message?.includes('wallet public key not found')) {
        throw new Error('Wallet does not control required keys');
      }

      if (attempt >= maxRetries) {
        throw new Error(`QuickSign failed after ${maxRetries} attempts: ${error.message}`);
      }

      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
};

Best Practices

Command Construction

✅ DO:

• Use unique nonces for each command

• Set reasonable gas limits

• Include all required capabilities

• Validate commands before QuickSign

• Use current timestamps

❌ DON'T:

• Reuse nonces across commands

• Set extremely high gas limits

• Forget required capabilities

• Skip command validation

User Experience

✅ DO:

• Group related transactions together

• Provide context about the operation

• Show estimated total cost

• Explain what will happen

• Handle rejections gracefully

❌ DON'T:

• Batch unrelated transactions

• Hide what transactions do

• Surprise users with unexpected txs

• Force re-approval on rejection

Security

✅ DO:

• Validate all user inputs

• Verify recipients before signing

• Check amounts are as expected

• Use appropriate gas settings

• Log all QuickSign operations

❌ DON'T:

• Trust user input blindly

• Sign transactions without review

• Use hardcoded private keys

• Skip error handling

Transaction Ordering

QuickSign does NOT guarantee transaction execution order. Each transaction is sent to the blockchain independently.

Sequential Execution

If you need guaranteed order:

// Sign all transactions with QuickSign
const signedTxs = await quickSign(commandSigDatas);

// Send them sequentially
for (const tx of signedTxs) {
  const result = await sendToBlockchain(tx);
  await pollUntilConfirmed(result.requestKey);
  // Wait for confirmation before sending next
}

Parallel Execution

For independent transactions:

// Sign all transactions
const signedTxs = await quickSign(commandSigDatas);

// Send all at once
const promises = signedTxs.map(tx => sendToBlockchain(tx));
const results = await Promise.all(promises);

Comparison with Single Sign

Feature	Single Sign	QuickSign
User Approvals	One per transaction	One for all
UX	Multiple popups	Single popup
Context	Individual txs	Full operation
Speed	Slower	Faster
Complexity	Simple	Moderate
Best For	Simple operations	Complex workflows

Debugging

Common Issues

"Command not valid JSON"

• Ensure cmd is JSON.stringify()-ed

• Check for circular references

• Validate JSON syntax

"Signer not found"

• Wallet doesn't control the public key

• Check key is correct (64 hex chars)

• Ensure wallet is unlocked

"Transaction failed after signing"

• Check Pact code for errors

• Verify sufficient balance

• Ensure capabilities are correct

Testing

Test QuickSign thoroughly:

// Test with Testnet first
const testQuickSign = async () => {
  const testCmd = {
    payload: {
      exec: {
        code: '(+ 1 1)',  // Simple test
        data: {}
      }
    },
    signers: [{
      pubKey: testPubKey,
      clist: [{ name: 'coin.GAS', args: [] }]
    }],
    meta: { /* testnet meta */ },
    networkId: 'testnet04',
    nonce: 'test'
  };

  try {
    const result = await window.kadena.request({
      method: 'kda_requestQuickSign',
      data: {
        networkId: 'testnet04',
        commandSigDatas: [{
          cmd: JSON.stringify(testCmd),
          sigs: [{ pubKey: testPubKey, sig: null }]
        }]
      }
    });

    console.log('QuickSign test successful:', result);
  } catch (error) {
    console.error('QuickSign test failed:', error);
  }
};

Browser Compatibility

QuickSign is available in:

• ✅ eckoWALLET Browser Extension (v2.0+)

• ✅ eckoWALLET Mobile via WalletConnect

Check for support:

if (window.kadena?.isKadena) {
  // eckoWALLET is present
  // QuickSign supported
  console.log('QuickSign available');
}

Related Documentation

• API Reference - Complete eckoWALLET API

• Transaction Signing - Single transaction signing

• dApp Integration Guide - Full integration tutorial

• Code Examples - More examples

Resources

• KIP-0015 Specification

• Chainweb Pact API

• Pact Documentation

Need Help?

• Discord: https://discord.com/invite/runonflux

• Twitter: @eckoWALLET

• GitHub: Report issues and feature requests

---

QuickSign makes complex DeFi operations simple. Use it to provide the best UX for your users! 🚀