stx-labs · yknl · Oct 22, 2020 · Oct 22, 2020 · Oct 22, 2020
diff --git a/packages/auth/README.md b/packages/auth/README.md
@@ -1,11 +1,13 @@
-# `auth`
+# @stacks/auth
 
-> TODO: description
+Construct and decode authentication requests for Stacks apps.
 
-## Usage
+## Installation
 
 ```
-const auth = require('auth');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/auth
 ```
+
+## Usage
+
+See [documentation](https://docs.blockstack.org/authentication/building-todo-app)
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -1,11 +1,13 @@
-# `@stacks/cli`
+# @stacks/cli
 
-> TODO: description
+Command line interface to interact with auth, storage and Stacks transactions.
 
-## Usage
+## Installation
 
 ```
-const cli = require('@stacks/cli');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/cli
 ```
+
+## Usage
+
+See [documentation](https://docs.blockstack.org/references/blockstack-cli)
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
@@ -23,7 +23,7 @@ import {
   estimateContractFunctionCall,
   SignedTokenTransferOptions,
   ContractDeployOptions,
-  ContractCallOptions,
+  SignedContractCallOptions,
   ReadOnlyFunctionOptions,
   ContractCallPayload,
   ClarityValue,
@@ -670,7 +670,7 @@ async function contractFunctionCall(network: CLINetworkAdapter, args: string[]):
     .then(answers => {
       functionArgs = parseClarityFunctionArgAnswers(answers, abiArgs);
 
-      const options: ContractCallOptions = {
+      const options: SignedContractCallOptions = {
         contractAddress,
         contractName,
         functionName,

diff --git a/packages/common/README.md b/packages/common/README.md
@@ -1,11 +1,9 @@
-# `common`
+# @stacks/common
 
-> TODO: description
+Common utilities used by Stacks.js packages.
 
-## Usage
+## Installation
 
 ```
-const common = require('common');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/common
 ```
diff --git a/packages/encryption/README.md b/packages/encryption/README.md
@@ -1,11 +1,9 @@
-# `encryption`
+# @stacks/encryption
 
-> TODO: description
+Encryption functions used by Stacks.js packages.
 
-## Usage
+## Installation
 
 ```
-const encryption = require('encryption');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/cli
 ```
diff --git a/packages/keychain/README.md b/packages/keychain/README.md
@@ -1,11 +1,9 @@
-# `keychain`
+# @stacks/keychain
 
-> TODO: description
+Create and manage keys/wallets for the Stacks blockchain.
 
-## Usage
+## Installation
 
 ```
-const keychain = require('keychain');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/keychain
 ```
diff --git a/packages/network/README.md b/packages/network/README.md
@@ -1,11 +1,9 @@
-# `network`
+# @stacks/network
 
-> TODO: description
+Network and API library for working with Stacks blockchain nodes.
 
-## Usage
+## Installation
 
 ```
-const network = require('network');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/network
 ```
diff --git a/packages/profile/README.md b/packages/profile/README.md
@@ -1,11 +1,9 @@
-# `profile`
+# @stacks/profile
 
-> TODO: description
+Functions for manipulating user profiles.
 
-## Usage
+## Installation
 
 ```
-const profile = require('profile');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/profile
 ```
diff --git a/packages/storage/README.md b/packages/storage/README.md
@@ -1,11 +1,9 @@
-# `storage`
+# @stacks/storage
 
-> TODO: description
+Store and fetch files with Gaia, the decentralized storage system.
 
-## Usage
+## Installation
 
 ```
-const storage = require('storage');
-
-// TODO: DEMONSTRATE API
+npm install @stacks/storage
 ```
diff --git a/packages/transactions/README.md b/packages/transactions/README.md
@@ -1,5 +1,5 @@
-# Stacks Transactions JS [![npm](https://img.shields.io/npm/v/@stacks/transactions?color=red)](https://www.npmjs.com/package/@stacks/transactions)
-The JavaScript library for generating Stacks (v2.0) transactions. 
+# @stacks/transactions [![npm](https://img.shields.io/npm/v/@stacks/transactions?color=red)](https://www.npmjs.com/package/@stacks/transactions)
+Construct, decode transactions and work with Clarity smart contracts on the Stacks blockchain.
 
 ## Installation
 

diff --git a/packages/transactions/src/builders.ts b/packages/transactions/src/builders.ts
@@ -301,7 +301,7 @@ export interface SignedMultiSigTokenTransferOptions extends TokenTransferOptions
  *
  * @param  {UnsignedTokenTransferOptions | UnsignedMultiSigTokenTransferOptions} txOptions - an options object for the token transfer
  *
- * @return {StacksTransaction}
+ * @return {Promis<StacksTransaction>}
  */
 export async function makeUnsignedSTXTokenTransfer(
   txOptions: UnsignedTokenTransferOptions | UnsignedMultiSigTokenTransferOptions
@@ -614,7 +614,6 @@ export interface ContractCallOptions {
   contractName: string;
   functionName: string;
   functionArgs: ClarityValue[];
-  senderKey: string;
   fee?: BigNum;
   feeEstimateApiUrl?: string;
   nonce?: BigNum;
@@ -626,6 +625,25 @@ export interface ContractCallOptions {
   sponsored?: boolean;
 }
 
+export interface UnsignedContractCallOptions extends ContractCallOptions {
+  publicKey: string;
+}
+
+export interface SignedContractCallOptions extends ContractCallOptions {
+  senderKey: string;
+}
+
+export interface UnsignedMultiSigContractCallOptions extends ContractCallOptions {
+  numSignatures: number;
+  publicKeys: string[];
+}
+
+export interface SignedMultiSigContractCallOptions extends ContractCallOptions {
+  numSignatures: number;
+  publicKeys: string[];
+  signerKeys: string[];
+}
+
 /**
  * Estimate the total transaction fee in microstacks for a contract function call
  *
@@ -679,15 +697,15 @@ export async function estimateContractFunctionCall(
 }
 
 /**
- * Generates a Clarity smart contract function call transaction
+ * Generates an unsigned Clarity smart contract function call transaction
  *
- * @param  {ContractCallOptions} txOptions - an options object for the contract function call
+ * @param {UnsignedContractCallOptions | UnsignedMultiSigContractCallOptions} txOptions - an options object for the contract call
  *
- * Returns a signed Stacks smart contract function call transaction.
- *
- * @return {StacksTransaction}
+ * @returns {Promise<StacksTransaction>}
  */
-export async function makeContractCall(txOptions: ContractCallOptions): Promise<StacksTransaction> {
+export async function makeUnsignedContractCall(
+  txOptions: UnsignedContractCallOptions | UnsignedMultiSigContractCallOptions
+): Promise<StacksTransaction> {
   const defaultOptions = {
     fee: new BigNum(0),
     nonce: new BigNum(0),
@@ -721,18 +739,27 @@ export async function makeContractCall(txOptions: ContractCallOptions): Promise<
     validateContractCall(payload, abi);
   }
 
-  const addressHashMode = AddressHashMode.SerializeP2PKH;
-  const privKey = createStacksPrivateKey(options.senderKey);
-  const pubKey = getPublicKey(privKey);
-
+  let spendingCondition = null;
   let authorization = null;
 
-  const spendingCondition = createSingleSigSpendingCondition(
-    addressHashMode,
-    publicKeyToString(pubKey),
-    options.nonce,
-    options.fee
-  );
+  if ('publicKey' in options) {
+    // single-sig
+    spendingCondition = createSingleSigSpendingCondition(
+      AddressHashMode.SerializeP2PKH,
+      options.publicKey,
+      options.nonce,
+      options.fee
+    );
+  } else {
+    // multi-sig
+    spendingCondition = createMultiSigSpendingCondition(
+      AddressHashMode.SerializeP2SH,
+      options.numSignatures,
+      options.publicKeys,
+      options.nonce,
+      options.fee
+    );
+  }
 
   if (options.sponsored) {
     authorization = new SponsoredAuthorization(spendingCondition);
@@ -768,17 +795,54 @@ export async function makeContractCall(txOptions: ContractCallOptions): Promise<
       options.network.version === TransactionVersion.Mainnet
         ? AddressVersion.MainnetSingleSig
         : AddressVersion.TestnetSingleSig;
-    const senderAddress = publicKeyToAddress(addressVersion, pubKey);
+    const senderAddress = c32address(addressVersion, transaction.auth.spendingCondition!.signer);
     const txNonce = await getNonce(senderAddress, options.network);
     transaction.setNonce(txNonce);
   }
 
-  if (options.senderKey) {
+  return transaction;
+}
+
+/**
+ * Generates a Clarity smart contract function call transaction
+ *
+ * @param  {SignedContractCallOptions | SignedMultiSigContractCallOptions} txOptions - an options object for the contract function call
+ *
+ * Returns a signed Stacks smart contract function call transaction.
+ *
+ * @return {StacksTransaction}
+ */
+export async function makeContractCall(
+  txOptions: SignedContractCallOptions | SignedMultiSigContractCallOptions
+): Promise<StacksTransaction> {
+  if ('senderKey' in txOptions) {
+    const publicKey = publicKeyToString(getPublicKey(createStacksPrivateKey(txOptions.senderKey)));
+    const options = omit(txOptions, 'senderKey');
+    const transaction = await makeUnsignedContractCall({ publicKey, ...options });
+
+    const privKey = createStacksPrivateKey(txOptions.senderKey);
     const signer = new TransactionSigner(transaction);
     signer.signOrigin(privKey);
-  }
 
-  return transaction;
+    return transaction;
+  } else {
+    const options = omit(txOptions, 'signerKeys');
+    const transaction = await makeUnsignedContractCall(options);
+
+    const signer = new TransactionSigner(transaction);
+    let pubKeys = txOptions.publicKeys;
+    for (const key of txOptions.signerKeys) {
+      const pubKey = pubKeyfromPrivKey(key);
+      pubKeys = pubKeys.filter(pk => pk !== pubKey.data.toString('hex'));
+      signer.signOrigin(createStacksPrivateKey(key));
+    }
+
+    for (const key of pubKeys) {
+      signer.appendOrigin(publicKeyFromBuffer(Buffer.from(key, 'hex')));
+    }
+
+    return transaction;
+  }
 }
 
 /**