algosdk 1.23.2 → 1.24.1

package/src/logicTemplates/htlc.js

@@ -0,0 +1,165 @@
+const sha256 = require('js-sha256');
+const { keccak256 } = require('js-sha3');
+const logic = require('../logic/logic');
+const logicSig = require('../logicsig');
+const templates = require('./templates');
+const transaction = require('../transaction');
+
+class HTLC {
+  /**
+   * HTLC allows a user to receive the Algo prior to a deadline (in terms of a round) by proving a knowledge
+   * of a special value or to forfeit the ability to claim, returning it to the payer.
+   * This contract is usually used to perform cross-chained atomic swaps
+   *
+   * More formally -
+   * Algos can be transferred under only two circumstances:
+   * 1. To receiver if hash_function(arg_0) = hash_value
+   * 2. To owner if txn.FirstValid > expiry_round
+   * ...
+   *
+   * @deprecated This feature will be removed in v2.
+   *
+   *Parameters
+   *----------
+   * @param {string} owner: an address that can receive the asset after the expiry round
+   * @param {string} receiver: address to receive Algos
+   * @param {string} hashFunction: the hash function to be used (must be either sha256 or keccak256)
+   * @param {string} hashImage: the hash image in base64
+   * @param {int} expiryRound: the round on which the assets can be transferred back to owner
+   * @param {int} maxFee: the maximum fee that can be paid to the network by the account
+   * @returns {HTLC}
+   */
+  constructor(owner, receiver, hashFunction, hashImage, expiryRound, maxFee) {
+    // don't need to validate owner, receiver - they'll be validated by template.insert
+    if (!Number.isSafeInteger(expiryRound) || expiryRound < 0)
+      throw Error(
+        'expiryRound must be a positive number and smaller than 2^53-1'
+      );
+    if (!Number.isSafeInteger(maxFee) || maxFee < 0)
+      throw Error('maxFee must be a positive number and smaller than 2^53-1');
+
+    let referenceProgramB64 = '';
+    if (hashFunction === 'sha256') {
+      referenceProgramB64 =
+        'ASAECAEACSYDIOaalh5vLV96yGYHkmVSvpgjXtMzY8qIkYu5yTipFbb5IH+DsWV/8fxTuS3BgUih1l38LUsfo9Z3KErd0gASbZBpIP68oLsUSlpOp7Q4pGgayA5soQW8tgf8VlMlyVaV9qITMQEiDjEQIxIQMQcyAxIQMQgkEhAxCSgSLQEpEhAxCSoSMQIlDRAREA==';
+    } else if (hashFunction === 'keccak256') {
+      referenceProgramB64 =
+        'ASAECAEACSYDIOaalh5vLV96yGYHkmVSvpgjXtMzY8qIkYu5yTipFbb5IH+DsWV/8fxTuS3BgUih1l38LUsfo9Z3KErd0gASbZBpIP68oLsUSlpOp7Q4pGgayA5soQW8tgf8VlMlyVaV9qITMQEiDjEQIxIQMQcyAxIQMQgkEhAxCSgSLQIpEhAxCSoSMQIlDRAREA==';
+    } else {
+      throw Error('hash function unrecognized');
+    }
+    // validate hashImage length
+    const hashImageBytes = Buffer.from(hashImage, 'base64');
+    if (hashImageBytes.length !== 32)
+      throw Error('hash image must be 32 bytes');
+
+    const referenceProgramBytes = Buffer.from(referenceProgramB64, 'base64');
+    const referenceOffsets = [
+      3 /* expiryRound */,
+      6 /* receiver */,
+      10 /* hashImage */,
+      42 /* owner */,
+      76,
+    ];
+    const injectionVector = [maxFee, expiryRound, receiver, hashImage, owner];
+    const injectionTypes = [
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.ADDRESS,
+      templates.valTypes.BASE64,
+      templates.valTypes.ADDRESS,
+    ];
+    const injectedBytes = templates.inject(
+      referenceProgramBytes,
+      referenceOffsets,
+      injectionVector,
+      injectionTypes
+    );
+    this.programBytes = injectedBytes;
+    const lsig = new logicSig.LogicSig(injectedBytes, undefined);
+    this.address = lsig.address();
+  }
+
+  /**
+   * returns the program bytes
+   * @returns {Uint8Array}
+   */
+  getProgram() {
+    return this.programBytes;
+  }
+
+  /**
+   * returns the string address of the contract
+   * @returns {string}
+   */
+  getAddress() {
+    return this.address;
+  }
+}
+
+/**
+ *  signTransactionWithHTLCUnlock accepts a transaction, such as a payment, and builds the HTLC-unlocking signature around that transaction
+ *
+ * @deprecated This feature will be removed in v2.
+ *
+ * @param {Uint8Array} contract : byte representation of the HTLC
+ * @param {Object} txn dictionary containing constructor arguments for a transaction
+ * @param {string} preImageAsBase64 : preimage of the hash as base64 string
+ *
+ * @returns {Object} Object containing txID and blob representing signed transaction.
+ * @throws error on validation failure
+ */
+function signTransactionWithHTLCUnlock(contract, txn, preImageAsBase64) {
+  const preImageBytes = Buffer.from(preImageAsBase64, 'base64');
+
+  // hash validation
+  const readResult = logic.readProgram(contract, undefined);
+  const ints = readResult[0];
+  const byteArrays = readResult[1];
+  const expectedHashedOutput = byteArrays[1];
+  const hashFunction = contract[contract.length - 15];
+  if (hashFunction === 1) {
+    const hash = sha256.create();
+    hash.update(preImageBytes);
+    const actualHashedOutput = Buffer.from(hash.hex(), 'hex');
+    if (!actualHashedOutput.equals(expectedHashedOutput)) {
+      throw new Error(
+        'sha256 hash of preimage did not match stored contract hash'
+      );
+    }
+  } else if (hashFunction === 2) {
+    const hash = keccak256.create();
+    hash.update(preImageBytes);
+    const actualHashedOutput = Buffer.from(hash.hex(), 'hex');
+    if (!actualHashedOutput.equals(expectedHashedOutput)) {
+      throw new Error(
+        'keccak256 hash of preimage did not match stored contract hash'
+      );
+    }
+  } else {
+    throw new Error('hash function in contract unrecognized');
+  }
+
+  const args = [preImageBytes]; // array of one element, the Uint8Array preimage
+
+  const lsig = new logicSig.LogicSig(contract, args);
+  // clear out receiver just in case
+  // eslint-disable-next-line no-param-reassign
+  delete txn.to;
+
+  const maxFee = ints[0];
+  // check fee
+  const tempTxn = new transaction.Transaction(txn);
+  if (tempTxn.fee > maxFee) {
+    throw new Error(
+      `final fee of payment transaction${tempTxn.fee.toString()}greater than transaction max fee${maxFee.toString()}`
+    );
+  }
+
+  return logicSig.signLogicSigTransaction(txn, lsig);
+}
+
+module.exports = {
+  HTLC,
+  signTransactionWithHTLCUnlock,
+};

package/src/logicTemplates/index.js

@@ -0,0 +1,20 @@
+const dynamicFeeTemplate = require('./dynamicfee');
+const htlcTemplate = require('./htlc');
+const limitOrderTemplate = require('./limitorder');
+const splitTemplate = require('./split');
+const periodicPayTemplate = require('./periodicpayment');
+
+module.exports = {
+  DynamicFee: dynamicFeeTemplate.DynamicFee,
+  getDynamicFeeTransactions: dynamicFeeTemplate.getDynamicFeeTransactions,
+  signDynamicFee: dynamicFeeTemplate.signDynamicFee,
+  HTLC: htlcTemplate.HTLC,
+  signTransactionWithHTLCUnlock: htlcTemplate.signTransactionWithHTLCUnlock,
+  LimitOrder: limitOrderTemplate.LimitOrder,
+  getSwapAssetsTransaction: limitOrderTemplate.getSwapAssetsTransaction,
+  Split: splitTemplate.Split,
+  getSplitFundsTransaction: splitTemplate.getSplitFundsTransaction,
+  PeriodicPayment: periodicPayTemplate.PeriodicPayment,
+  getPeriodicPaymentWithdrawalTransaction:
+    periodicPayTemplate.getPeriodicPaymentWithdrawalTransaction,
+};

package/src/logicTemplates/limitorder.js

@@ -0,0 +1,227 @@
+const address = require('../encoding/address');
+const makeTxn = require('../makeTxn');
+const group = require('../group');
+const logic = require('../logic/logic');
+const logicSig = require('../logicsig');
+const nacl = require('../nacl/naclWrappers');
+const templates = require('./templates');
+const utils = require('../utils/utils');
+
+class LimitOrder {
+  /**
+   * MakeLimitOrder allows a user to exchange some number of assets for some number of algos.
+   * Fund the contract with some number of Algos to limit the maximum number of
+   * Algos you're willing to trade for some other asset.
+   *
+   * Works on two cases:
+   * * trading Algos for some other asset
+   * * closing out Algos back to the originator after a timeout
+   *
+   * trade case, a 2 transaction group:
+   * gtxn[0] (this txn) Algos from Me to Other
+   * gtxn[1] asset from Other to Me
+   *
+   * We want to get _at least_ some amount of the other asset per our Algos
+   * gtxn[1].AssetAmount / gtxn[0].Amount >= N / D
+   * ===
+   * gtxn[1].AssetAmount * D >= gtxn[0].Amount * N
+   *
+   * close-out case:
+   * txn alone, close out value after timeout
+   *
+   * @deprecated This class will be removed in v2.
+   *
+   * Constructor Parameters:
+   * @param {string} owner: the address to refund funds to on timeout
+   * @param {int} assetid: the ID of the transferred asset
+   * @param {int} ratn: exchange rate (N asset per D Algos, or better)
+   * @param {int} ratd: exchange rate (N asset per D Algos, or better)
+   * @param {int} expiryRound: the round at which the account expires
+   * @param {int} minTrade: the minimum amount (of Algos) to be traded away
+   * @param {int} maxFee: maximum fee used by the limit order transaction
+   * @returns {LimitOrder}
+   */
+  constructor(owner, assetid, ratn, ratd, expiryRound, minTrade, maxFee) {
+    // don't need to validate owner - it will be validated by template.insert
+    if (!Number.isSafeInteger(assetid) || assetid < 0)
+      throw Error('assetid must be a positive number and smaller than 2^53-1');
+    if (!Number.isSafeInteger(ratn) || ratn < 0)
+      throw Error('ratn must be a positive number and smaller than 2^53-1');
+    if (!Number.isSafeInteger(ratd) || ratd < 0)
+      throw Error('ratd must be a positive number and smaller than 2^53-1');
+    if (!Number.isSafeInteger(expiryRound) || expiryRound < 0)
+      throw Error(
+        'expiryRound must be a positive number and smaller than 2^53-1'
+      );
+    if (!Number.isSafeInteger(minTrade) || minTrade < 0)
+      throw Error('minTrade must be a positive number and smaller than 2^53-1');
+    if (!Number.isSafeInteger(maxFee) || maxFee < 0)
+      throw Error('maxFee must be a positive number and smaller than 2^53-1');
+
+    const referenceProgramB64 =
+      'ASAKAAEFAgYEBwgJCiYBIP68oLsUSlpOp7Q4pGgayA5soQW8tgf8VlMlyVaV9qITMRYiEjEQIxIQMQEkDhAyBCMSQABVMgQlEjEIIQQNEDEJMgMSEDMBECEFEhAzAREhBhIQMwEUKBIQMwETMgMSEDMBEiEHHTUCNQExCCEIHTUENQM0ATQDDUAAJDQBNAMSNAI0BA8QQAAWADEJKBIxAiEJDRAxBzIDEhAxCCISEBA=';
+    const referenceProgramBytes = Buffer.from(referenceProgramB64, 'base64');
+    const referenceOffsets = [
+      5 /* minTrade */,
+      7 /* assetID */,
+      9 /* ratd */,
+      10 /* ratn */,
+      11 /* expiryRound */,
+      12 /* owner */,
+      16,
+    ];
+    const injectionVector = [
+      maxFee,
+      minTrade,
+      assetid,
+      ratd,
+      ratn,
+      expiryRound,
+      owner,
+    ];
+    const injectionTypes = [
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.ADDRESS,
+    ];
+    const injectedBytes = templates.inject(
+      referenceProgramBytes,
+      referenceOffsets,
+      injectionVector,
+      injectionTypes
+    );
+    this.programBytes = injectedBytes;
+    const lsig = new logicSig.LogicSig(injectedBytes, undefined);
+    this.address = lsig.address();
+    this.owner = owner;
+    this.assetid = assetid;
+  }
+
+  /**
+   * returns the program bytes
+   * @returns {Uint8Array}
+   */
+  getProgram() {
+    return this.programBytes;
+  }
+
+  /**
+   * returns the string address of the contract
+   * @returns {string}
+   */
+  getAddress() {
+    return this.address;
+  }
+}
+
+/**
+ * returns a group transactions array which transfer funds according to the contract's ratio
+ *
+ * @deprecated This feature will be removed in v2.
+ *
+ * @param {Uint8Array} contract: byteform of the contract from the payer
+ * @param {int} assetAmount: the amount of assets to be sent
+ * @param {int} microAlgoAmount: number of microAlgos to transfer
+ * @param {Uint8Array} secretKey: secret key for signing transaction
+ * @param {int} fee: the fee per byte to pay in microAlgos
+ * @param {int} firstRound: the first round on which these txns will be valid
+ * @param {int} lastRound: the last round on which these txns will be valid
+ * @param {string} genesisHash: the b64-encoded genesis hash indicating the network for this transaction
+ * @returns {Uint8Array}
+ * the first payment sends money (Algos) from contract to the recipient (we'll call him Buyer), closing the rest of the account to Owner
+ * the second payment sends money (the asset) from Buyer to the Owner
+ * these transactions will be rejected if they do not meet the restrictions set by the contract
+ * @throws error if arguments fail contract validation
+ */
+function getSwapAssetsTransaction(
+  contract,
+  assetAmount,
+  microAlgoAmount,
+  secretKey,
+  fee,
+  firstRound,
+  lastRound,
+  genesisHash
+) {
+  const buyerKeyPair = nacl.keyPairFromSecretKey(secretKey);
+  const buyerAddr = address.encodeAddress(buyerKeyPair.publicKey);
+  const programOutputs = logic.readProgram(contract, undefined);
+  const ints = programOutputs[0];
+  const byteArrays = programOutputs[1];
+
+  let noCloseRemainder;
+  let noAssetRevocationTarget;
+  const contractAssetID = ints[6];
+  const contractOwner = address.encodeAddress(byteArrays[0]);
+  const lsig = logicSig.makeLogicSig(contract, undefined);
+  const contractAddress = lsig.address();
+  const algosForAssets = makeTxn.makePaymentTxn(
+    contractAddress,
+    buyerAddr,
+    fee,
+    microAlgoAmount,
+    noCloseRemainder,
+    firstRound,
+    lastRound,
+    undefined,
+    genesisHash,
+    undefined
+  );
+  const assetsForAlgos = makeTxn.makeAssetTransferTxn(
+    buyerAddr,
+    contractOwner,
+    noCloseRemainder,
+    noAssetRevocationTarget,
+    fee,
+    assetAmount,
+    firstRound,
+    lastRound,
+    undefined,
+    genesisHash,
+    undefined,
+    contractAssetID
+  );
+  const txns = [algosForAssets, assetsForAlgos];
+  const txGroup = group.assignGroupID(txns);
+
+  const ratd = ints[7];
+  const ratn = ints[8];
+  if (assetAmount * ratd < microAlgoAmount * ratn) {
+    throw new Error(
+      `bad payment ratio, ${assetAmount.toString()}*${ratd.toString()} !>= ${microAlgoAmount.toString()}*${ratn.toString()}`
+    );
+  }
+  const minTrade = ints[4];
+  if (microAlgoAmount < minTrade) {
+    throw new Error(
+      `payment amount ${microAlgoAmount.toString()} less than minimum trade ${minTrade.toString()}`
+    );
+  }
+  const maxFee = ints[2];
+  if (txGroup[0].fee > maxFee) {
+    throw new Error(
+      `final fee of payment transaction ${txGroup[0].fee.toString()} greater than transaction max fee ${maxFee.toString()}`
+    );
+  }
+  if (txGroup[1].fee > maxFee) {
+    throw new Error(
+      `final fee of asset transaction ${txGroup[1].fee.toString()} greater than transaction max fee ${maxFee.toString()}`
+    );
+  }
+
+  const algosForAssetsSigned = logicSig.signLogicSigTransactionObject(
+    txGroup[0],
+    lsig
+  );
+  const assetsForAlgosSigned = txGroup[1].signTxn(secretKey);
+  return utils.concatArrays(algosForAssetsSigned.blob, assetsForAlgosSigned);
+}
+
+module.exports = {
+  LimitOrder,
+  getSwapAssetsTransaction,
+};

package/src/logicTemplates/periodicpayment.js

@@ -0,0 +1,208 @@
+const address = require('../encoding/address');
+const makeTxn = require('../makeTxn');
+const logic = require('../logic/logic');
+const logicSig = require('../logicsig');
+const nacl = require('../nacl/naclWrappers');
+const templates = require('./templates');
+
+class PeriodicPayment {
+  /**
+   * MakePeriodicPayment allows some account to execute periodic withdrawal of funds.
+   * This is a contract account.
+   *
+   * This allows receiver to withdraw amount every
+   * period rounds for withdrawWindow after every multiple
+   * of period.
+   *
+   * After expiryRound, all remaining funds in the escrow
+   * are available to receiver.
+   *
+   * @deprecated This class will be removed in v2.
+   *
+   * Constructor Parameters:
+   * @param {string} receiver: address which is authorized to receive withdrawals
+   * @param {int} amount: the amount to send each period
+   * @param {int} withdrawalWindow: the duration of a withdrawal period
+   * @param {int} period: the time between a pair of withdrawal periods
+   * @param {int} expiryRound: the round at which the account expires
+   * @param {int} maxFee: maximum fee used by the withdrawal transaction
+   * @param {string} lease: b64 representation of lease to use, or leave undefined to generate one
+   * @returns {PeriodicPayment}
+   */
+  constructor(
+    receiver,
+    amount,
+    withdrawalWindow,
+    period,
+    expiryRound,
+    maxFee,
+    lease
+  ) {
+    // don't need to validate receiver or lease, it's validated by template insert
+    this.receiver = receiver;
+    if (!Number.isSafeInteger(amount) || amount < 0)
+      throw Error('amount must be a positive number and smaller than 2^53-1');
+    this.amount = amount;
+    if (!Number.isSafeInteger(withdrawalWindow) || withdrawalWindow < 0)
+      throw Error(
+        'withdrawalWindow must be a positive number and smaller than 2^53-1'
+      );
+    this.withdrawalWindow = withdrawalWindow;
+    if (!Number.isSafeInteger(period) || period < 0)
+      throw Error('period must be a positive number and smaller than 2^53-1');
+    this.period = period;
+    if (!Number.isSafeInteger(expiryRound) || expiryRound < 0)
+      throw Error(
+        'expiryRound must be a positive number and smaller than 2^53-1'
+      );
+    this.expiryRound = expiryRound;
+    if (!Number.isSafeInteger(maxFee) || maxFee < 0)
+      throw Error('maxFee must be a positive number and smaller than 2^53-1');
+    this.maxFee = maxFee;
+
+    if (lease === undefined) {
+      const leaseBytes = nacl.randomBytes(32);
+      this.lease = Buffer.from(leaseBytes).toString('base64');
+    } else {
+      this.lease = lease;
+    }
+
+    this.programBytes = this.getProgram();
+    const lsig = new logicSig.LogicSig(this.programBytes, undefined);
+    this.address = lsig.address();
+  }
+
+  /**
+   * returns the program bytes
+   * @returns {Uint8Array}
+   */
+  getProgram() {
+    const referenceProgramB64 =
+      'ASAHAQYFAAQDByYCIAECAwQFBgcIAQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIIJKvkYTkEzwJf2arzJOxERsSogG9nQzKPkpIoc4TzPTFMRAiEjEBIw4QMQIkGCUSEDEEIQQxAggSEDEGKBIQMQkyAxIxBykSEDEIIQUSEDEJKRIxBzIDEhAxAiEGDRAxCCUSEBEQ';
+    const referenceProgramBytes = Buffer.from(referenceProgramB64, 'base64');
+    const referenceOffsets = [
+      4 /* period */,
+      5 /* withdrawWindow */,
+      7 /* amount */,
+      8 /* expiryRound */,
+      9 /* lease */,
+      12 /* receiver */,
+      46,
+    ];
+    const injectionVector = [
+      this.maxFee,
+      this.period,
+      this.withdrawalWindow,
+      this.amount,
+      this.expiryRound,
+      this.lease,
+      this.receiver,
+    ];
+    const injectionTypes = [
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.INT,
+      templates.valTypes.BASE64,
+      templates.valTypes.ADDRESS,
+    ];
+    return templates.inject(
+      referenceProgramBytes,
+      referenceOffsets,
+      injectionVector,
+      injectionTypes
+    );
+  }
+
+  /**
+   * returns the string address of the contract
+   * @returns {string}
+   */
+  getAddress() {
+    return this.address;
+  }
+}
+
+/**
+ * getPeriodicPaymentWithdrawalTransaction returns a signed transaction extracting funds form the contract
+ *
+ * @deprecated This feature will be removed in v2.
+ *
+ * @param {Uint8Array} contract: the bytearray defining the contract, received from the payer
+ * @param {int} fee: the fee per byte for the transaction
+ * @param {int} firstValid: the first round on which the txn will be valid
+ * @param {string} genesisHash: the hash representing the network for the txn
+ * @returns {Object} Object containing txID and blob representing signed transaction
+ * @throws error on failure
+ */
+function getPeriodicPaymentWithdrawalTransaction(
+  contract,
+  fee,
+  firstValid,
+  genesisHash
+) {
+  const readResult = logic.readProgram(contract, undefined);
+  const ints = readResult[0];
+  const byteArrays = readResult[1];
+  const period = ints[2];
+  const duration = ints[4];
+  const amount = ints[5];
+  if (firstValid % period !== 0) {
+    throw new Error(
+      `firstValid round ${firstValid.toString()} was not a multiple of contract period ${period.toString()}`
+    );
+  }
+
+  // extract receiver and convert as needed
+  const receiverBytes = byteArrays[1];
+  const receiver = address.encodeAddress(receiverBytes);
+  // extract lease and convert
+  const leaseBuffer = byteArrays[0];
+  const lease = new Uint8Array(leaseBuffer);
+  const lastValid = firstValid + duration;
+  const to = receiver;
+  let noCloseRemainder;
+  let noNote;
+  const lsig = logicSig.makeLogicSig(contract, undefined);
+  const from = lsig.address();
+  const txn = {
+    from,
+    to,
+    fee,
+    amount,
+    closeRemainderTo: noCloseRemainder,
+    firstRound: firstValid,
+    lastRound: lastValid,
+    note: noNote,
+    genesisHash,
+    genesisID: '',
+    type: 'pay',
+    lease,
+  };
+
+  // check fee
+  const tempTxn = makeTxn.makePaymentTxn(
+    from,
+    to,
+    fee,
+    amount,
+    noCloseRemainder,
+    firstValid,
+    lastValid,
+    noNote,
+    genesisHash,
+    ''
+  );
+  if (tempTxn.fee > ints[1]) {
+    throw new Error(
+      `final fee of payment transaction${tempTxn.fee.toString()}greater than transaction max fee${ints[1].toString()}`
+    );
+  }
+
+  return logicSig.signLogicSigTransaction(txn, lsig);
+}
+module.exports = {
+  PeriodicPayment,
+  getPeriodicPaymentWithdrawalTransaction,
+};