Add docs to contract.ts (counterfactual#19)

* Add docs to contract.ts

* Rename "truffle artifact" to "build artifact"

packages/contracts/test/integration/commitReveal.spec.ts

@@ -62,22 +62,22 @@ enum Player {
 }
 
 describe("CommitReveal", async () => {
-  const ConditionalTransfer = AbstractContract.loadTruffleArtifact(
+  const ConditionalTransfer = AbstractContract.loadBuildArtifact(
     "ConditionalTransfer"
   );
-  const StaticCall = AbstractContract.loadTruffleArtifact("StaticCall");
-  const NonceRegistry = AbstractContract.loadTruffleArtifact("NonceRegistry");
-  const Registry = AbstractContract.loadTruffleArtifact("Registry");
-  const Signatures = AbstractContract.loadTruffleArtifact("Signatures");
-  const Transfer = AbstractContract.loadTruffleArtifact("Transfer");
+  const StaticCall = AbstractContract.loadBuildArtifact("StaticCall");
+  const NonceRegistry = AbstractContract.loadBuildArtifact("NonceRegistry");
+  const Registry = AbstractContract.loadBuildArtifact("Registry");
+  const Signatures = AbstractContract.loadBuildArtifact("Signatures");
+  const Transfer = AbstractContract.loadBuildArtifact("Transfer");
 
-  const StateChannel = AbstractContract.loadTruffleArtifact("StateChannel", {
+  const StateChannel = AbstractContract.loadBuildArtifact("StateChannel", {
     StaticCall,
     Signatures,
     Transfer
   });
 
-  const CommitRevealApp: AbstractContract = AbstractContract.loadTruffleArtifact(
+  const CommitRevealApp: AbstractContract = AbstractContract.loadBuildArtifact(
     "CommitRevealApp",
     {
       StaticCall

packages/test-utils/src/contract.ts

@@ -1,29 +1,50 @@
-import { TruffleContract } from "@counterfactual/typescript-typings";
+import { BuildArtifact } from "@counterfactual/typescript-typings";
 import * as ethers from "ethers";
 import { HIGH_GAS_LIMIT } from "./utils";
 
 const { solidityKeccak256 } = ethers.utils;
 
+/**
+ * Simple wrapper around ethers.Contract to include information about Counterfactual instantiation.
+ */
 export class Contract extends ethers.Contract {
   public salt?: string;
   public cfAddress?: string;
   public registry?: Contract;
 }
 
+/**
+ * Convenience class for an undeployed contract i.e. only the ABI and bytecode.
+ */
 export class AbstractContract {
-  public static loadTruffleArtifact(
+  /**
+   * Load build artifact by name into an abstract contract
+   * @example
+   *  const CountingApp = AbstractContract.loadBuildArtifact("CountingApp", {StaticCall});
+   * @param artifactName The name of the artifact to load
+   * @param links Optional AbstractContract libraries to link.
+   * @returns Truffle artifact wrapped in an AbstractContract.
+   */
+  public static loadBuildArtifact(
     artifactName: string,
     links?: { [name: string]: AbstractContract }
   ): AbstractContract {
+    // TODO: Load build artifacts manually once we move away from Truffle
     const truffleContract = artifacts.require(artifactName);
-    return AbstractContract.fromTruffleContract(truffleContract, links);
+    return AbstractContract.fromBuildArtifact(truffleContract, links);
   }
 
-  public static fromTruffleContract(
-    truffleContract: TruffleContract,
+  /**
+   * Wrap build artifact in abstract contract
+   * @param buildArtifact Truffle contract to wrap
+   * @param links Optional AbstractContract libraries to link.
+   * @returns Truffle artifact wrapped in an AbstractContract.
+   */
+  public static fromBuildArtifact(
+    buildArtifact: BuildArtifact,
     links?: { [name: string]: AbstractContract }
   ): AbstractContract {
-    let { bytecode } = truffleContract;
+    let { bytecode } = buildArtifact;
     if (links) {
       for (const name of Object.keys(links)) {
         const library = links[name];
@@ -35,44 +56,70 @@ export class AbstractContract {
         bytecode = bytecode.replace(regex, addressHex);
       }
     }
-    const abstractContract = new AbstractContract(
-      truffleContract.abi,
-      bytecode
-    );
-    const networkNames = Object.keys(truffleContract.networks);
+    const abstractContract = new AbstractContract(buildArtifact.abi, bytecode);
+    const networkNames = Object.keys(buildArtifact.networks);
     if (networkNames.length !== 0) {
       const networkName = networkNames.sort()[0];
       abstractContract.deployedAddress =
-        truffleContract.networks[networkName].address;
+        buildArtifact.networks[networkName].address;
     }
     return abstractContract;
   }
 
   private deployedAddress?: string;
 
-  constructor(readonly abi: string[], readonly binary: string) {}
+  /**
+   * @param abi ABI of the abstract contract
+   * @param binary Binary of the abstract contract
+   */
+  constructor(readonly abi: string[] | string, readonly binary: string) {}
 
+  /**
+   * Get the deployed singleton instance of this abstract contract, if it exists
+   * @param signer Signer (with provider) to use for contract calls
+   * @throws Error if AbstractContract has no deployed address
+   */
   public getDeployed(signer: ethers.Wallet): Contract {
     if (!this.deployedAddress) {
       throw new Error("Must have a deployed address");
     }
     return new Contract(this.deployedAddress, this.abi, signer);
   }
 
+  /**
+   * Deploy new instance of contract
+   * @param signer Signer (with provider) to use for contract calls
+   * @param args Optional arguments to pass to contract constructor
+   * @returns New contract instance
+   */
   public async deploy(signer: ethers.Wallet, args?: any[]): Promise<Contract> {
     return new Contract("", this.abi, signer).deploy(
       this.binary,
       ...(args || [])
     );
   }
 
+  /**
+   * Connect to a deployed instance of this abstract contract
+   * @param signer Signer (with provider) to use for contract calls
+   * @param address Address of deployed instance to connect to
+   * @returns Contract instance
+   */
   public async connect(
     signer: ethers.Wallet,
     address: string
   ): Promise<Contract> {
     return new Contract(address, this.abi, signer);
   }
 
+  /**
+   * Deploys new contract instance through a Counterfactual Registry
+   * @param signer Signer (with provider) to use for contract calls
+   * @param registry Counterfactual Registry instance to use
+   * @param args Optional arguments to pass to contract constructor
+   * @param salt Optional salt for Counterfactual deployment
+   * @returns Contract instance
+   */
   public async deployViaRegistry(
     signer: ethers.Wallet,
     registry: Contract,

packages/typescript-typings/types/counterfactual/index.d.ts

@@ -1,4 +1,4 @@
-export interface TruffleContract {
+export interface BuildArtifact {
   readonly contractName: string;
   readonly abi: any[];
   readonly bytecode: string;