Index
b'[](https://circleci.com/gh/endless-nameless-inc/cheshire/tree/master)\n[](https://coveralls.io/github/endless-nameless-inc/cheshire?branch=master)\n\n# Cheshire\n\nCheshire enables fast CryptoKitties dApp development by providing local implementations of the CryptoKitties web API and smart contracts. It features:\n\n1. An **Ethereum testnet** running the CryptoKitties smart contracts\n\n2. An HTTP server running a **minimal implementation of the CryptoKitties web API**:\n * `/kitties`\n * `/kitties/:id`\n * `/user/:address`\n\n3. A simple **Node.js framework** for seeding the development environment with realistic data and bootstraping your dApp\n\nCheshire has simplified and accelerated development at [Endless Nameless](http://endlessnameless.com) considerably. We\'re excited to share it.\n\n## Installation\n\nYou can install Cheshire with git or as a [Truffle Box](http://truffleframework.com/boxes/).\n\n### Git\n\n```bash\ngit clone http://github.com/endless-nameless-inc/cheshire\ncd cheshire\nyarn install\n```\n\n### Truffle box\n\n```bash\ntruffle unbox endless-nameless-inc/cheshire\n```\n\n## Usage\n\nCheshire is meant to be used with the [Truffle Framework](http://truffleframework.com/), but can function as a standalone service, depending on your workflow.\n\n### Start Cheshire\n\nTo start Cheshire, run:\n\n`yarn start`\n\nThis does the following:\n\n1. Starts an Ethereum testnet ([ganache-cli](https://github.com/trufflesuite/ganache-cli))\n2. Deploys CryptoKitties\'s [KittyCore](https://etherscan.io/address/0x06012c8cf97bead5deae237070f9587f8e7a266d#code), [SaleClockAuction](https://etherscan.io/address/0xb1690c08e213a35ed9bab7b318de14420fb57d8c#code), and [SiringClockAuction](https://etherscan.io/address/0xc7af99fe5513eb6710e6d5f44f9989da40f27f26#code) contracts to the testnet\n3. Starts a local CryptoKitties API server\n4. Executes `/scripts/setup.js`\n\nThe output should look something like this:\n\n```\n> Starting database...\n> Starting testnet...\n> Compiling contracts...\n> Deploying CryptoKitties contracts to testnet...\n> Starting local CryptoKitties API server...\n> Running setup script...\n\nCheshire is live \xf0\x9f\x98\xba Here\'s what\'s inside:\n\nAvailable Accounts\n====================\n(0) 0x182fc09c33fdd6c2f5b2562f3ca721fa954689c8\n ...\n(9) 0xcdf40e926a778d93429b72c341b4a9e0ee8624c4\n\nPrivate Keys\n====================\n(0) 0x76a67ae288fd67ea8d4f7fb94f50c36b606d9448db579584af90d52105f9d8cf\n ...\n(9) 0x6e77cfded732de6d423abcaccc45ee8c4bdc2eb3c0c47938acb386ac17c496b8\n\nTestnet Contracts\n====================\nKittyCore: 0xa751b62893867d0608a2ada5d17d0c43e3433040\nSaleClockAuction: 0x1ab49d53d0bff0202ec4b330349b427155bba7ac\nSiringClockAuction: 0x671843106e07f9d835d7299381cd14863af18593\n\nServices\n====================\nEthereum testnet listening on port 8546\nCryptoKitties API listening on port 4000\nCheshire dashboard available at http://localhost:4000\n\nView the above at any time by running `yarn run help`\n```\n\nEureka! When Cheshire\'s running, you have your very own local copy of CryptoKitties, enabling you to build your dApp with the speed and convenience of testnet. Let\'s try it out.\n\n### Interacting with your local CryptoKitties API\n\nCheshire automatically imports the Genesis kitty. To fetch the Genesis kitty from your local CryptoKitties API, run:\n\n```bash\n$ curl http://localhost:4000/kitties/1\n```\n\nThe response should look exactly like the response returned by CryptoKitties\'s [production API](https://api.cryptokitties.co/kitties/1).\n\nSee the [scripts](#scripts) section below to learn how to seed your environment with more data.\n\n### Interacting with the testnet contracts\n\nTo interact with the testnet contracts, start by opening a Truffle console:\n\n```bash\n$ truffle console --network cheshire\n```\n\nThen, taking note of the KittyCore testnet address displayed when you started Cheshire, create an instance of KittyCore, and use the `getKitty` function to fetch the Genesis kitty\'s genes:\n\n```bash\ntruffle(cheshire)> // Be sure to replace the KittyCore address below\ntruffle(cheshire)> kittyCore = KittyCore.at(\'0xa751b62893867d0608a2ada5d17d0c43e3433040\')\ntruffle(cheshire)> kittyCore.getKitty(1)\n```\n\nThe response should be pretty similar to the one you get from the [mainnet contract](https://etherscan.io/address/0x06012c8cf97bead5deae237070f9587f8e7a266d#readContract).\n\n## Suggested Conventions\n\nYou\'ll get the most out of Cheshire by adopting these conventions:\n\n* Store your contracts in the `/contracts` directory\n* Design the web application layers of your stack to reference Cheshire\'s [environment variables](#cheshire-environment-variables) (hat tip to the [twelve-factor](https://12factor.net) methodology)\n* Update your [setup script](#setup-script) to deploy your contracts to testnet\n* Update your [setup script](#setup-script) to start your dApp\'s web application\n\n## Scripts\n\nCheshire provides a simple scripting framework designed to help seed the development environment with realistic data, primarily by importing kitties from mainnet.\n\nA Cheshire script is just a Node.js module that runs in the context of the Cheshire environment.\n\nHere\'s an example of a script that imports a [Bug Cat](https://www.cryptokitties.co/kitty/101) from mainnet to your testnet.\n\n```js\n// /scripts/import-bug-cat.js\nmodule.exports = async function importBugCat(cheshire) {\n const bugCatIdMainnet = 101\n const ownerTestnet = cheshire.accounts[0].address\n const kittyIdTestnet = await cheshire.importKitty(bugCatIdMainnet, ownerTestnet)\n\n console.log(`Kitty #${kittyIdTestnet} => ${ownerTestnet}`)\n}\n```\n\nTo run this script, you would execute the following command:\n\n```sh\n$ yarn run script ./scripts/import-bug-cat.js\n```\n\nThe output would look something like:\n\n```txt\nKitty #2 => 0x182fc09c33fdd6c2f5b2562f3ca721fa954689c8\n```\n\n### Setup Script\n\nCheshire executes `/scripts/setup.js` when started. You should update the `setup.js` shipped with Cheshire to:\n\n1. Deploy your dApp\'s contracts to testnet. For example:\n\n ```\n const kittyRace = await cheshire.deployContract(\'KittyRace\', process.env.ADDRESS_KITTY_CORE)\n log(\'KittyRace deployed at:\', kittyRace.address)\n ```\n\n2. Start your dApp\'s web application, so it inherits the various [environment variables](#cheshire-environment-variables) set by Cheshire.\n\n We recommend adopting the convention in the `setup.js` shipped with Cheshire which simply expects the `APP_START` environment variable to contain a command that starts your dApp\'s web application.\n\n For example:\n\n ```\n APP_START="cd ~/Projects/kittyrace-web; bundle exec rails server" yarn start\n ```\n\nYou can run any script in place of `setup.js` by passing its path to `yarn start`. This is handy for setting up specific scenarios, such as a KittyRace with 9 registered racers:\n\n```sh\nyarn start ./scripts/setup-registered-racers.js 9\n```\n\n### Cheshire API Reference\n\nCheshire scripts receive an instance of the Cheshire class with these methods:\n\n#### `accounts()`\nReturns array of available Ethereum accounts (the same accounts defined in config.json)\n\n#### `contractAddress(contractName)`\nReturns address of `contractName`\n\n#### `contractInstance(contractName)`\nReturns an instance of `contractName` as a `web3.eth.contract` object\n\n#### `createKitty(matronId, sireId, generation, genes, owner, apiObject)`\nCreate a kitty with the given parameters.\n\nReturns the kitty\'s ID.\n\n#### `async deployContract(contractName, ...constructorArgs)`\nDeploy `contractName` to testnet.\n\nCheshire compiles all contracts in `/contracts` at start time. Expects `/contracts/ContractName.sol` to exist.\n\nReturns an instance of `contractName` as a `web3.eth.contract` object\n\n#### `async importKitty(kittyIdMainnet, ownerTestnet)`\nImport a kitty from mainnet, and assign it to `ownerTestnet`\n\nReturns the testnet kitty\'s ID.\n\n#### `async importUser(addressMainnet, addressTestnet)`\nImport user\'s profile and kitties from mainnet, and assign to `addressTestnet`.\n\nReturns address of testnet user.\n\n### Cheshire Environment Variables\n\nCheshire sets several environment variables before running any script:\n\n* `ADDRESS_KITTY_CORE`\n* `ADDRESS_SALE_CLOCK_AUCTION`\n* `ADDRESS_SIRING_CLOCK_AUCTION`\n* `URL_CRYPTO_KITTIES_API`\n\nIn addition to these, the address for any contract deployed with a Cheshire script will be stored in an environment variable named with the convention, `ADDRESS_