Skip to content
Scratch 3 extensions for Ethereum contracts
JavaScript Shell Dockerfile Solidity
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Better defaults for watching for events May 21, 2019
build/contracts Added Contract Address reporter block May 11, 2019
contracts Added extension for Basic Non-Fungible Token (NFT) May 9, 2019
docs WIP Token Tutorial May 23, 2019
heroku/scripts Added Heroku release script May 8, 2019
scripts Initial WIP commit May 8, 2019
test Initial WIP commit May 8, 2019
.dockerignore Initial WIP commit May 8, 2019
.gitattributes Initial WIP commit May 8, 2019
.gitignore Added build contracts and config May 8, 2019
LICENSE Initial WIP commit May 8, 2019 Changed the event queues into more generalised queues that can be use… May 21, 2019
jest.config.js Initial WIP commit May 8, 2019
package-lock.json Merge changes from other laptop Jun 6, 2019
package.json Merge changes from other laptop Jun 6, 2019


a Scratch 3.0 extension for interacting with Ethereum contracts.

Token Blocks


A Scratch 3.0 server with the Ethereum extensions has been made publicly available at

To load an Ethereum extension, click the Add Extension button on the bottom left of the Scratch UI.

Add Extension

Even though the applicatoin is served on a content delivery network (CDN), it can still take some time to download as the JavaScript file lib.min.js is nearly 20 MB in size.

Quick Start

The easiest way to play with the extensions locally is to run a Docker container.

mkdir scratch
cd scratch
git clone
cd eth-scratch3
npm install
docker build -t eth-scratch3 --target web .
docker run -p 8601:8601 -e PORT=8601 eth-scratch3

After the server starts, Scratch should be available at http://localhost:8601

Table of Contents


What is Scratch?

Scratch is a project of the Lifelong Kindergarten Group at the MIT Media Lab. It is provided free of charge.

Scratch is designed especially for ages 8 to 16, but is used by people of all ages. Millions of people are creating Scratch projects in a wide variety of settings, including homes, schools, museums, libraries, and community centers.

Scratch 3.0

Scratch 3.0 is the latest generation of Scratch, launched on January 2, 2019. It is designed to expand how, what, and where you can create with Scratch. It includes dozens of new sprites, a totally new sound editor, and many new programming blocks. And with Scratch 3.0, you’re able to create and play projects on your tablet, in addition to your laptop or desktop computer.

Scratch 3.0 Extensions

In the Scratch editor, you can add collections of extra blocks called extensions.

The Scratch Team will be publishing specifications and guidelines for extensions in the future. Once available, you will be able to submit extensions to the Scratch Team for consideration in the official Scratch 3.0 extensions library. We’ll also provide guidelines for developing and distributing "experimental" extensions, which can be used to create projects on individual computers, but not shared in the Scratch online community.

Hacking Scratch 3.0 Extensions

Although Scratch extension specifications have not been released, a few people in the community have worked out how to hack together a Scratch 3.0 extension. Most of the work in this repository is based on the blog post How to Develop Your Own Block for Scratch 3.0.

An example Scratch game Scratch Wars.

Scratch Block Error Handling

There is no native error handling in Scratch so the best you can do is watch the Browser's console. In Chrome, View -> Developer -> JavaScript Console. Longer term, a hat event block for errors should be created so errors can be fed back into the Scratch application.

For more Scratch information, see the Scratch FAQ.

Scratch 3.0 Extension Development


The following software must be installed before running the installation steps


The following will install this Eth Scratch 3 repository and the Scratch repositories scratch-gui and scratch-vm. This will allow Scratch with the custom extensions to be run locally.

mkdir scratch
cd scratch
git clone
cd eth-scratch3
npm install

# install the scratch gui and vm packages
cd ..
git clone
cd scratch-gui
npm install
cd ..
git clone
cd scratch-vm
npm install
npm install web3@0.20.3
npm link
cd ../scratch-gui
npm link scratch-vm

# link crypto beasts to the scratch vm extensions
cd ../scratch-vm/src/extensions
ln -s ../../../eth-scratch3/scratch/extensions ./custom
# Link the extension to Truffle's deployed contract information
cd ../../../eth-scratch3/scratch/extensions/
ln -s ../../build/contracts contracts

# Copy modified scratch vm and gui files into the dependent packages
cd ../
cp gui/index.jsx ../../scratch-gui/src/lib/libraries/extensions/index.jsx
cp vm/extension-manager.js ../../scratch-vm/src/extension-support/extension-manager.js

# start the Scratch React App
cd ../../scratch-gui
npm start

After the server starts, Scratch should be available at http://localhost:8601


The following steps are done in the above but a listed here for anyone who wants to write their own Scratch extension.

New extensions are registered in the scratch-gui project in the src/lib/libraries/extensions/index.jsx file. Add this to the extensions array

    name: (
            defaultMessage="Detailed, mintable, burnable token"
            description="Name of extension"
    extensionId: 'tokenDetailedMintableBurnable',
    collaborator: 'Nick Addison',
    // iconURL: boostIconURL,
    // insetIconURL: boostInsetIconURL,
    description: (
            defaultMessage="A detailed ERC20 token that is mintable and burnable"
            description="Description of extension"
    featured: true,
    disabled: false,
    bluetoothRequired: false,
    internetConnectionRequired: true

The JavaScript in the extension file needs to be loaded via the src/extension-support/extension-manager.js file in the scratch-vm package. Add the following function property to the builtinExtensions object in the src/extension-support/extension-manager.js file

tokenDetailedMintableBurnable: () => require('../extensions/custom/tokenDetailedMintableBurnable'),


In order to deploy the contracts with the public test networks using Truffle, the config.js file needs to be updated with your private key and Infura project id. See Introducing the Infura Dashboard for details on how to get an Infura project id.

To deploy the token contract to the Ropsten public test network.

npx truffle migrate --reset --network ropsten

The extension for the basic ERC20 contract currently works with the 0x999D5f944DD6f97911b2f854638d1fDEe297bE3F contract deployed to the Ropsten testnet.

Smart Contracts

The contracts used by the Scratch extensions are based off Open Zeppelin contract.


MetaMask is a browser extension that allows users to manage their Ethereum private keys in a variety of ways, including hardware wallets, while isolating them from the site context. MetaMask comes pre-loaded connections to Ethereum main and test networks via Infura.

See MetaMask Developer Documentation for more details on how to interact with MetaMask. 10 Web3/Metamask Use Cases Every Blockchain Developer Needs to Know is also very useful. The official Web3.js 0.2x.x documentation also helps.


This Dockerfile will add the Scratch extensions like Detailed, mintable, burnable token to the Scratch 3.0 react app and copy it into a nginx image. This image can then be deployed to a cloud provider. This project is currently using Heroku, but others like AWS, Azure and GCP will also work.

npm run buildWebImage will build the Docker image which runs

docker build -t --target web .

npm run bashWebImage will shell into the built web image

docker run -it sh

npm run runWebImage will run the Scratch 3.0 react app with extensions locally

docker run -p 8601:8601 -e PORT=8601

npm run pushWebImage will push the web image up to the Heroku container registry

docker push

This project is deploying to Heroku hence the image names. These will need to be changed if deploying to other cloud-based container registries.


The Scratch playground with Ethereum extensions has been deploed to an AWS S3 bucket called This is made publically available via Static Website hosting at endpoint

To speed up the delivery of the static files, AWS CloudFront is used a content delivery network (CDN). The CloudFront distribution domain name is

AWS Route 53 has the DNS records to route the subdomain to the CloudFront distribution. Speficically, it has A and AAAA alias records to route IPv4 and IPv6 addresses.

The partent domain is managed by netregistry. It delegates responsibility for the subdomain to Route 53 by adding a NS records. A separate NS record is created for each of the four name services in the Route 53 service.

AWS Certificate Manager is used to issue the certificate for the subdomain. This is required for the secure https connections to the CloudFront distribution.

See Creating a Subdomain That Uses Amazon Route 53 as the DNS Service without Migrating the Parent Domain for more information.

Continuous Integration

CicleCi is used for CI. The config file is .circleci/config.yml. The CircleCi jobs can be viewed at

Currently, builds are automatically pushed to Heroku This will probably change to AWS in the future.


  • Read state of sent transactions. eg pending or number of confirmations
  • Need to convert event args that are integers from strings to numbers
  • Hat event block for feeding back errors
  • Extension for full ERC721 non-fungible tokens
  • Events for Ether blocks. eg account balance changes
  • Generating an extension from a contract’s ABI
  • Integrating Assist.js for easier onboarding
  • Extension that uses Web3.js 1.x
  • Extension that uses Ethers.js
You can’t perform that action at this time.