Here is the GitHub repository containing the setup and description of how to perform the demos.

For those interested in gaining a deeper understanding of zk-SNARKs, the slides from a presentation I gave last year that is mostly focused around the BCTV14/15 proving protocol are available here.

At my work, we use ASP.NET MVC 5. With it, we use what I suspect is the most common T4 template: T4MVC. While this fancy template solves a lot of problems, it turned into a very large one for our team.

We have a lot of changes occurring and a lot more feature requests in our backlog. Originally, the files that T4MVC was generating were tracked in version control. As you can imagine, the generated files were a constant source of conflicts in a moderately-size team that made a massive amount of changes.

I wanted to ignore generated files. It took a while to get everyone on board, but we finally stopped tracking all the generated and merge conflicts became a less-frequent occurrence. Rejoice! (This was one of my demands when I instigated the change in how we use Git.)

There was one issue, though. While we could ignore CSS and JS files, and regenerate them easily, we found that we couldn't get T4MVC to run outside of Visual Studio. This means that we'd have to re-generate the files while in Visual Studio. This wasn't too much of a problem, since there are extensions for regenerating T4 templates.

In addition to ignoring generated files, I suggested that we use Pull Requests (believe it or not, we weren't using them!). This suggestion was initially not taken and developers manually merged their changes into the integration branch prior to code-review, but I saw it as a temporary compromise.

I reformulated and figured I'd just nudge everyone into using them when I could. I set up all of my branches that others had to collaborate on as protected and required devs that worked off of them to create PRs. I used them in other circumstances as well, and would make hints on how they make code-review easier for those that don't want to diff from the command-line. I think it worked, because the decision to start using PRs was made.

As we were planning how we'd get everyone to use PRs, I pushed for branch policies, automated builds, and build verification before merging. We then researched how we'd actually do it. We soon ran into the T4MVC issue again, this time finding the exact reason why it only worked inside VS.

Now the decision to use automated builds has been made, but the T4MVC issue still exists. While the decision to go back to tracking the generated files and foregoing build-verification was made, this wouldn't do for me, and I looked into ways to generate the helper classes of T4MVC outside of Visual Studio.

There are a lot of abandoned attempts I made: forking SharpDevelop and using their DTE with T4MVC.tt (there is a neglected fork out there — couldn't escape a circular dependency issue due to how the Host behaved), a complete re-implementation using Scripty (Scripty is too broken), implementing a hacky version of Scripty using Buildalyzer (ran into strange dependency errors) to try to more-or-less follow the previous approach, implement a hacky version of Buildalyzer using the MSBuild APIs so I could implement a hackier version of Scripty) because it was a much smaller project than the other starting points (and easy to follow/experiment with).

With great Googling, I eventually found T4MVCCoreLite and looked through the commits and found that the code came from the R4MVC project. I down-ported it to ASP.NET MVC 5 using what I learned in the abandoned attempts, got some code generated, and then took the latest R4MVC tip and did it all over again. (We couldn't just use plain R4MVC since it's for ASP.NET Core MVC.)

It worked!

Here's the repo!

I'm sitting cross-legged today, clanking on my custom X210 ThinkPad — a modded X201 with new internals (8th gen i7, 32GB DDR4, 512GB NVMe SSD). I'm performing my routine monthly search for a programming language that doesn't suck, and I'm being pedantic as usual and blowing off any language that doesn't have string interpolation and support for lamdas. I'm trying a few languages that I don't think I'll immediately hate by coding up the traditional "Hello, World!" to see if I like the feel.

Unaware of the typographical error I made, I compile the program. I run it. The console prints out:

Hell, World!

Suddenly, I'm in junior high again. My father is a computer scientist that somehow thinks that what he does is cool. I don't want to do that boring crap. I want to make funny animations and whatnot. I've been getting more and more into Macromedia Flash, but lately I've had some ideas for silly games and I hacked up ActionScript to sort of make them work.

I run my latest game. It starts up and it actually works! The music is playing, too! Wow, that was easy! Just listen to the reggae—wait, what's that I hear?

My father is fidgeting with his keys at the front door, trying to make it back into our home. He is coming home from his boring banal work where he was debugging some code for some lame spaceship. I rush over to the door, and try to unlock it before he does. It's a draw.

"Look at this game I made!" I eagerly shout. I drag him over to our family computer, an iMac — we only use Apple computers at home.

He looks at the game.

I had taken an image of Bob Marley, vectorized it, made an animation where his mouth moved like a ventriloquist's dummy, and created an object for it with key-frames where it was facing four different directions. I put this object in a Pac-Man like game that I managed to get actually working (despite some bugs).

"It's called 'Pac-Marley'," I says.

He chuckles.

"Play it," I command, all sly-like.

"Okay," he says. He starts to play it.

As he plays, I duplicitously say, "Listen to the music," and turn up the volume almost to the max. It's "Stir it Up." He chuckles again and continues playing. He apparently was a Pac-Man professional in his youth and makes a comment about the buggy behavior that I hadn't figured out how to fix.

Right as he completes the level, the computer screams and shakes a picture of the girl for The Exorcist. Father is startled. I explain to him that I didn't want to try to make more levels, so I made it jump-scare at the end of the first-and-only level, instead.

Conversation continues . . . and now it's almost after dinner. He's trying to show me what the kind of programming he does is. He goes and audibly digs through all the books in his closest.

As I finish the meal, he comes back into the kitchen with the book. It's a C++ book he found from his college-days. He flips through some of the pages, and points at some of the code, spouting esoteric terms that sounds like it might be Elvish.

"That looks harder than ActionScript," I say.

"It's easy," he says. "Look, I'll show you."

He gets his black work laptop, and opens up a text editor, and says, "Alright, come here."

I go there. Now he wants me to sit at the computer and type.

Alright, he says. "I added some standard imports for you."

"What?"

He explains, but I don't understand. I pretend to, though, and nod my head. He quickly explains the main(...) function to me, but I don't understand why it has to return a number, or even what "returning" really is in this context.

He continues explaining to me, and starts telling me things to type. After the main() function is right and we have this thing called cout, he gives me more instructions.

"Alright, now do two 'less-than's," he says.

"Like this?" I ask, uncertain because it seemed a little strange.

"Yep," he says. "Now in quotation marks, type 'Hello, World', add a semi-colon at the end, and then click this button," he says, pointing to a button of the text-editor.

"Should there be a comma after the 'Hello' in 'Hello, World'?" I ask.

He is unsure. I decide to use a comma, and then I click the button that he pointed out. A console appears. The console prints out:

Hell, World!

He laughs, because neither of us caught the typo until now. I get up from the laptop at this point. It was more work than the Pac-Marley game and not as interesting. If that's what programming is, I don't want to do it. I'll stick to making animations on the iMac.

As part of the migration, I manually copied over the blog posts, and while I was at it, I figured I'd publish most of the hitherto un-published blog posts (at least the ones that didn't look unfinished). The only substantive blog post that hasn't yet been published is a mammoth of a post that applied the SOLID principles to Solidity. In retrospect, I should've split that one up into five parts, since that was the post that was a bit too daunting to get out of the door all-at-once, and this blog basically stagnated as a result.

I think I'll revisit the "SOLIDity" topic soon. I have to update the code examples now because the language has changed quite a bit since I originally started the article.

As it should be.

Recently, I've taken the plunge into the thick mire of crypto-Twitter, and I must say it is fairly repugnant. Among the handful of individuals that I beforehand knew were genuinely worth following I've found bots, terrible investment advice, mystical trend analysis, desperate speculators, and self-professed experts that I've never heard of. I'm holding my nose and trying to find where it doesn't reek, but I realized something, I think.

Crypto has gone mainstream with the peak of December 2017. Or, at least, it has gone mainstream for the younger generation. Most have heard of it. Sure, not many know extensively about it, but that is the case with most things that have gone mainstream.

I remember how things were in 2013. I remember how things were in 2014 and 2015. While we're currently mirroring 2014 to a degree, there is a slight difference that I can't yet articulate.

Let's see if we can find it? (The rest of this post will be an attempted search for articulation—a true essay.)

Late 2016–2017 was riddled with ICOs and shady scams to a much greater extent of the altcoins of 2012–2013.

Maybe one difference is that there are so many people that haven't caught on—they've still got deranged hope in all of these projects or think that things will take off soon? . . . But there  were people thinking that in 2014. History shows that it didn't happen. So, it's not that.

This last round, I think more people have lost more money, though they may not realize it yet. But lots lost in 2014—that Magic the Gathering Online Exchange (yes the biggest crypto exchange at the time was originally for a card game) was probably the biggest disaster—the crypto Hindenburg—in the space. There wasn't even a single precipitating factor in the last crash—it was simply just an overblown bubble.

Meetup attendance, at first glance, appears to be more or less the same. The number of attendees is a function of the market cap. What may be strange is that the number of attendees per meetup is roughly the same as this time in 2014. But that's per meetup—there's a lot more meetups now, and other than the core community that attends as much as they can, I think most attendees of meetups are picking what's closest to them.

Actually, maybe it essentially is just like 2014 (only at a slightly larger scale?). The difference may merely rest in me: I, no longer a poor student, and am more of a participant this round. I didn't care that much about the price in 2014—most projects were uninteresting or obvious scams. Now, I still don't care much about the price (by all means, Bitcoin, go ahead and fall to 3K already)—but there are a few interesting projects these days.

When I say "a few," I mean a few. Like, less than 7.

What is G.I.T.?

G.I.T. is a version control software, so it's like any other version control software you might've used in the past. Feel free to use it like it's CVS, Subversion, ClearCase, TFS, or anything else! It really doesn't matter. Emoji smiling face!

The Recommended Approach

For large teams, the following approach is what we've found to work best. Please note that we have only experimented with this approach, and haven't been compelled to try another approach because it just seems to work so well.

Infinite Indefinite Branches

This just sounds cool, so we went with it, even though we don't really know what it means. In practice, we've found ourselves only maintaining two indefinite branches, but you could extend this and have as many indefinite branches as you wanted. These are branches that'll go on until the end of time—you'll live forever through your commits, so strive for as many as you can!

While you can have as many indefinite branches as you want, you'll definitely want the two types of branches we have. We have a master branch, where all development is done, and a Release branch, where all the code in the next scheduled release lives.

The master Branch

Developers are free to update master as often as they want and however they want.

• Want to make sweeping changes that are far beyond the scope of your task? No problem—merge conflicts are fun!
• Don't want to test that your random refactors at least maintain basic functionality? Go ahead—if QA doesn't catch any errors, that's their problem since it's their job anyway!
• Developing on the master branch is great, because you can implement your changes using code that hasn't been released yet—it's like you're coding in the future! The best part about this is that, as time goes on, you're using more and more unreleased code, and you may not even know it! Neat-o!
• We also would like to suggest that no one on your team tells anyone else about what changes they've made (make all your changes a delightful surpise!), and developers should try to complete tasks without any code review when they can so as not to busy up anyone else.
• Oh, and make sure to track all generated files! This will keep development convenient by shaving off a couple of seconds by not having to manually regenerate files locally!
• Don't provide commit messages that describe your changes other than what you feel like expressing—who are you to decide what message describes a commit?

The Release Branch

Yes, this branch is named in PascalCase while the master branch was named in camelCase. Inconsistency is fun! When it comes time to release the next version of the project into the production environment, you'll probably need to try to get the changes made in the master branch into the Release branch (but this is not always the case: sometimes you can just tell people that a feature was released without actually having to release it—it's like magic!). When you do have to actually release a new set of features and bugfixes, make sure to follow these nice tidbits of wisdom we've gleaned:

• Have none of the people that initially coded the features be involved in the process. Seeing code through to the end of its journey isn't the responsibility of a developer—a developer 'develops', not 'completes' (otherwise they'd be called 'completers')!
• Use cherry-picks as the sole means of getting changes from the master branch to the Release branch. Instead of using some kind of process where each feature is implemented on its own branch and then merged, this approach means we can cherry-pick each of the individual commits that were made on a task. Cherries are delicious—pick as many as you can!
• If the work implementing a feature was done in multiple commits, know that you don't need to cherry-pick in chronological order. For any merge conflicts that you don't feel like resolving, just take the source everytime—it doesn't matter!  Likewise, if there were two tasks, task A and task B, and task B makes changes to changes introduced in task A—again, it doesn't really matter if you cherry-pick task B first. Nothing matters, because God is dead!  

Conclusion

In this short guide we have covered everything that G.I.T. is best used for and described the ideal version control development process. The best part of this process is that the branches will diverge farther and farther as the master branch ends up with more and more unreleased code and the Release branch gets more and more cherry-picks resulting in more and more interesting histories. This is totally a sustainable model, and we highly recommend it to anyone.

Please don't actually follow any of the advice in this post.

An Introduction to Git

Git is a version-control system (VCS)—sometimes called a source-control manager (SCM).

A crucial part in understanding Git is understanding the context that resulted in its creation.

1969–1982

Unix-based operating systems saw fairly widespread use in academic institutions and computer nerds of the day liked it because it was modular, self-contained, and aimed at programmers. Trouble was, Unix was proprietary, owned by AT&T, and licenses to use it had restrictions (which could make it a gray-area to change the OS to support whatever program you were working on).

Enter Richard Matthew Stallman

In 1983, in a Usenet post, Richard Matthew Stallman kicked off the Free Software Movement by annoucing his project: a completely free, open-source operating system. Because he is a computer nerd, he called it 'GNU'—which stands for 'GNU, Not Unix' (nerdy recursion joke). The project was to basically replace Unix but have the same "feel."

1991

GNU was still not fully complete (many utility programs used in most operations were implemented). The kernel (which manages CPU access, RAM access, memory, devices, hardware, and system calls) was the remaining thing to be finished.

Enter Linus Torvalds: a Finnish guy who wrote his own free, open-source kernel that used the GNU utils, and named it Linux.

2005

Linux has become very, very prevalent. Used everywhere.
See this archived Wikipedia article to see the state of Linux adoption in 2005. (Linux is currently the largest software development project on the planet. It is the basis for Android, ChromeOS, and far too many other things to list.)

A large chunk of the kernel is drivers for various hardware that only bloats as time goes on. Another chunk is a lot of networking stuff. Loads and loads of people contributing to the repository and making pull requests daily.

Probably not that much fun to maintain if you're Linus, right?

Right.

To simplify events, Linus was annoyed with the version control tool he was using, so he wrote a new one in a weekend.

He made sure his new tool:

• had users working on local copies of the repository
• had support for distributed merging
• could allow for easy renaming of files
• was fast
• was open source

Linus named this new tool 'Git'—named after himself, since 'Git' means 'an unpleasant person'. You may be entertained to glance over the original Git readme from the first ever Git commit on GitHub. Git has seen widespread use partly due to GitHub.

Basic Git

Here's a couple of interactive tutorials that should familiarize you with Git.

• https://try.github.io/
• https://learngitbranching.js.org/

Our Version Control Process

Git is flexible and can be used in many ways, some more incorrect than others. Much of the remainder of this guide outlines the version control process we will use.

Features

We need to think in terms of 'features' instead of 'tasks'. We don't want to integrate changes if the feature is not complete. This means if server-side code is finished, but styles are not complete, the changes for the server-side code should not be merged into the integration branch until the client-side styles and scripts are complete.

The convention in Git—in fact, the default—is to name the primary, working branch "master". We will adhere to this convention.

Don't Be Afraid of Merging!

If you aren't familiar with Git but are familiar with other SCMs, merging may have been quite painful for you in the past.

Git was designed for easy merging, and because of its light underlying cryptography, this is possible. We will use branching in Git with branches for features and these branches will get merged together. That is, we will use Git as intended.

It should be noted that it can be somewhat difficult to merge two branches that have diverged due to lack of proper maintenance. It is also difficult if the branches have had changes brought in from one-another in a way that circumvents the underlying cryptography as it is usually used, losing the link between data that Git uses to make merging easy.

Key Workflow Points

• Features get their own branches (even for simple text changes—because branches are simple!)  The benefits of having a branch for each feature are:  we will not "lose" commits anymore we will not have to constantly resolve merge conflicts when releasing features that have multiple commits associated with them we will not have the problem of commits being applied in the "wrong order"    
• There is one beta branch used for integration, code reviews, and testing
• "Merge resolutions" between two features with conflicting changes get their own branches  This will afford us the benefit of being able to choose which features get released. If, for example, there are two features—feature A and feature B—in development, there are four possible release-related situations that can occur:  feature A and feature B are both being released only feature A is being released only feature B is being released neither feature is being released   By having the 'resolution branch' instead of fixing the merge conflicts between the two features on the beta branch directly, and then having to later track down the merge in the beta branch (and filter through other merges and beta-branch-only changes), we can simply select the correct branch for our release scenario.  
• Releases get their own branches

General Workflow

At the start of an iteration/sprint, the master branch, the beta (integration) branch, and the most recent prod (release) branch all have the exact same changes. All feature branches "branch-off" from the master branch.

• Feature branches get updated by the developers of the feature at the discretion of the developers.
• The beta branch will get updated as features are completed.
• The master branch will get updated during the next release, and a new prod branch will be created from the master branch and it will be "frozen" where no additional changes will be made to that particular release branch (except for hotfixes, which will be explained in another section). This process continues indefinitely, or until the sun explodes.

Feature Branches

A 'feature' ('work request') may be broken up into multiple 'tasks', where some tasks are dependent upon others.

The following steps are applicable for tasks that are not dependent upon other tasks. For tasks that are dependent on other tasks, refer to the "Dependent Task Workflow" section.

At the start of an iteration, you will checkout the master branch and ensure that you have the latest changes. This can be achieved via your favorite Git-friendly command prompt with:

git checkout master
git pull

You will then create a new branch for your feature.
Remember, you must create the new branch from the master branch.
To check your current branch, you can run:

git status

You should see something like:

On branch master
nothing to commit, working directory clean

After you are sure you are on the master branch, you are ready to create your new feature branch. Let's say the work request number is 654321. This can be done as follows:

git checkout -b dev/f00654321

Now you can do as many commits as your heart desires! However, please refrain from committing anything that doesn't compile.

To commit all your changes (use discretion):

git add .
git commit -m " #654321 Enter short description here"

NOTE: If you are putting the task number at the start of your commit message starting with a '#' so that TFS will track the commit for you, put an extra space in before the '#' since '#' is also the default comment character when rebasing interactively. If you forget the space, your commit message could potentially disappear when the changes are moved back into the master branch.

It is also recommended that you run the following command after your first commit on the new feature branch:

git push -u origin dev/f00654321

This will push the changes in your branch up to origin (TFS in our case). That way if your computer explodes or is stolen, your changes aren't lost. Pushing the changes up to origin is fine because your changes are on your branch only and don't step on anyone else's tasks. Having the changes on origin also means that that multiple developers can easily collaborate on a single feature-branch.

Once the feature branch is being tracked by origin, you update it with your following local commits by simply doing:

git push

Integrating Changes

Once you are finished with your feature and you're sure your code will work perfectly and that you've covered every edge case, it may be time to merge the changes into the beta branch.

NOTE: If your is task still requires front-end CSS/styles, don't merge the changes into beta yet. The front-end work is a dependent task and the feature is not complete. In such cases, make a note in the testing dialog that your task is not to be tested until the dependent task(s) are complete. Send your code for review and notify the developers of the dependent tasks that they may begin. Only once a feature is fully implemented should the following commands be entered.

git checkout beta
git pull
git merge dev/t00654321 --squash
git commit
git push

If you see output pertaining to merge conflicts, follow the steps in the "Handling Merge Conflicts" subsection.

Once the merge on beta is pushed up to origin, update all the affected files on the beta environment.

At least one task should be sent for review at this point:

• If your task had no dependent tasks, send the task for review.
• If your task had dependent tasks, your task should've already been sent to review at this point, but the dependent task(s) should be sent for review at the current juncture.

Handling Merge Conflicts

It's possible you could experience a merge conflict when attempting to merge your feature branch into the beta branch. This is because you changed a line in your feature branch that someone else changed in their feature branch, and they have already merged their changes into the beta branch.

If you see something like:

Auto-merging change
CONFLICT (add/add): Merge conflict in change
Squash commit -- not updating HEAD
Automatic merge failed; fix conflicts and then commit the result.

then there is a merge conflict.

Step 1: Finding the Conflicting Files

In the case of a merge conflict, you'll want to determine what feature your changes are conflicting with. To do that, we'll find the conflicting files and refer to the history.

You might more-easily be able to determine the conflicting files from Visual Studio instead of issuing the following commands.

The output when initially attempting the merge will give you a hint at what files are conflicting, but for another way to easily see which files conflict, enter:

git status

If there are a quite a few files conflicting, then the output generated when attempting the merge or when entering git status might become a little too cluttered. To list only the conflicting files, enter (or paste):

git diff --name-only --diff-filter=U

(It may be handy to copy and paste this outputted list into notepad.)

If the only conflicting files are generated/minified files, then we will permit a manual merge resolution on the beta branch and you can exit the rest of the "Handling Merge Conflicts" process. Essentially, in the case of generated/minified files, you just take one version or the other of the conflicting file to make Git shut up and regenerate the file before committing. You'd then continue whatever process you were going through before encountering the 'bogus' merge conflict.

(My preference is to put all generated file types in the .gitignore file and just be rid of this pain-point.)

Step 2: Canceling the Merge

Why cancel the merge on beta if there is a genuine merge conflict?

It's important that we don't accept changes that create conflicts and require cascading merge commits directly on the beta branch so that, when time comes to release only some tasks, we can pick the tasks needed and merge them with absolutely no effort at all.

Now that we know all the files that are conflicting, we can go ahead and abort the merge. This can be done by entering the following:

git reset --hard HEAD

Step 3: Finding the Conflicting Author

You might more-easily be able to determine the conflicting author from Visual Studio instead of issuing the following commands.

Now we'll see what feature(s) introduced conflicting changes and figure out who we need to beat up work with:

git log CONFLICTING_FILE_PATH_HERE

Replace 'CONFLICTING_FILE_PATH_HERE' with the path to your conflicting file. This will show the history of the given file.

NOTE: Git plays nicer with Linux/Unix-like paths with forward slashes instead of back slashes, so be wary of tabbing causing issues with paths? TODO: Update this if it isn't an issue (not on a Windows machine at the time of writing . . .)

A more advanced command is:

git log master..beta

Which will list all the commits that beta has that master doesn't.
(There may be some noise with revert commits, but those can be ignored since they "cancel out" commits that were 'undone'/'removed' from beta.)

An even more advanced command is:

git log master..beta -- CONFLICTING_FILE_PATH_HERE

Which will list all the commits affecting the given file that beta has that master doesn't. This is probably the command you'd want to use.

One of these commands should show you the commit messages and help you figure out who you'll need to Slack/work-with to create a resolution branch.

Step 4: Creating the Resolution Branch

Communicate with the developer(s) of the conflicting feature and determine which of the two features would take the least amount of effort to modify in order to be compatible with the other.

Once the easier-to-alter feature and the harder-to-alter feature have been identified, checkout the branch of the harder-to-alter feature.

git fetch
git checkout dev/f00harder-to-alter

(NOTE: instead of 'harder-to-alter' and 'easier-to-alter', use the actual WR numbers.)

Create a new resolution branch from the harder-to-alter branch.

git checkout -b dev/f00harder-to-alter-f00easier-to-alter

For example, creating a resolution branch between a WR 654321 and a WR 765432 would look like:

git checkout -b dev/f00654321-f00765432

Then begin the merge of the changes from the easier-to-alter branch (which, we know will conflict):

git merge --squash dev/f00easier-to-alter 

Resolve the conflicts with your favorite merge tool or manually.

Once the conflicts are resolved and committed, we'll push the resolution branch to origin:

git push -u origin dev/f00harder-to-alter-f00easier-to-alter

Make sure the developers of both features look at the result of the final merge and ensure that no behaviors were altered or broken.

Update the implementation dialog on both tasks in TFS to say something similar to the following:

If this task is being released with task [CONFLICTING_TASK], merge this branch instead of the two task branches: [RESOLUTION_BRANCH]

Step 5: 'Removing' the First of the Two Conflicting Features from beta

Once you and the developer that worked on the other branch with conflicting changes have created a resolution branch, one of you will need to remove the original feature branch  that was pushed up to beta. This is so that we can merge the new resolution branch instead and get both of the originally-conflicting features onto the beta branch without conflicts.

Since we "squash merge" feature tasks onto the beta branch to begin with, all we have to do is revert the "squash merge" commit for that feature.

Let's say the commit-hash of the first of the conflicting features on beta that we're going to remove was deadbeefcafe. We enter:

git revert deadbeefcafe

Then, we squash merge the resolution branch:

git merge --squash dev/f00harder-to-alter-f00easier-to-alter
git commit

Now we update the beta environment with the affected files and continue whatever process wee were working on prior (probably would send task to review at this point).

Dependent Task Workflow

The dependent task workflow is fairly simple, from the perspective of someone working a dependent task. Let's say you are such a person.

You have some changes to do on top of someone else's changes. That person's changes have not yet completed the feature.

Simply checkout the branch they were working on:

git fetch
git checkout dev/00654321

Commit your changes to that branch.

If your changes complete the feature, jump to the "Integrating Changes" subsection of the "General Workflow" section.

Related Task Workflow

Related tasks should be identified at the beginning of an iteration before any code has been written in order to come up with a release strategy that calls for this workflow, since the related tasks can effectively become dependent on code written/changed in the other task(s) and create a situation where it becomes difficult to release one task without releasing the other.

Potential pattern if must use code written in another unreleased feature:

git fetch
git checkout dev/00654321
git checkout -b dev/f00876543

If a related task must be released without the initial task where some code was written also being released, we could potentially cherry-pick the code the related task uses, and then cherry-pick/rebase the related task changes, but this could complicate the release of the branch where the code was cherry-picked from.

Releasing Features

Check the corresponding task descriptions for notes about resolution branches. If there are resolution branches between two features, and both features are being released, use that branch instead of each feature branch individually.

For simplicity, let's say you were releasing a feature1, a feature2, and a feature3:

git checkout master
git merge feature1 feature2 feature3
git push
git checkout -b prod/v1.3.0
git push -u origin prod/v1.3.0

And you're done!

If any features were not included in the release and they are on the beta environment, the "squash merge" commits for those features should be reverted on the beta branch if the features are not scheduled for the next release. This is so development branches do not diverge from the production code.

Any tasks still in development should at this point be rebased on top of the latest changes in the master branch.

Rebasing Currently In-Development Features

When changes are released, the master branch is updated and a new release branch was created. If you are working on a task still, you'll need to update your feature branch with the changes that are currently in production.

To do this, first make sure you have the latest changes in both your feature branch (if you were collaborating with someone else) and the latest changes in the master branch.

git checkout master
git pull
git checkout dev/f00654321
git pull

In order to get the latest changes, we'll simply merge the master branch into the feature branch, and then rebase our changes so that they are "on top of" the latest master branch changes.

git merge master
git rebase

Hotfixes

Unfortunately, things don't always go perfect and sometimes emergency fixes need to be performed after some code has gone live.

Checkout the lastest release branch:

git checkout prod/v1.3.0

You can optionally create a new branch from this release branch for your hotfix changes:

git checkout -b hotfix/v1.3.0

Or, create a new, incremented release branch:

git checkout -b prod/v1.3.1

Or just make a new commit on the current release branch.

Once the hotfix has been implemented and committed, we'll get the fix on the relevant branches.

If you took the option with a hotfix/vX.X.X type of branch, you'd then do:

git push -u origin hotfix/v1.3.0
git checkout prod/v1.3.0
git merge hotfix/v1.3.0
git push

If you went with the incremented version release branch with the hotfix directly on that branch:

git push -u origin prod/v1.3.1

If you went with the hotfix committed directly on the latest release branch, you'd do:

git push

You now need to get your hotfix into the master branch. The release branch is directly mergable if there are no other commits in the release branch that should not go into the master branch (potentially something like livelocaloverride being committed).

If there are no differences other than the hotfix commit:

git checkout master
git merge prod/v1.3.1
git push

Alternatively, the hotfix commit can be cherry-picked. This would most likely be done if there were other commits on the release branch that for some reason shouldn't get merged back into the master branch.

Let's say the hotfix commit hash was deadbeefcafe.

git checkout master
git cherry-pick deadbeefcafe -x
git push

Send a slack to the team channel and tell the devs that they'll have to rebase their current in-progress feature branches now that the master branch has been updated.

Our Branch Name Conventions

The following are set of rules not enforced by Git. They are merely conventions that we will adhere to.

Feature Branches

• All features are developed in their own branches.
• We will begin by using the convention "dev/f{paddedWrNumber}", where paddedWrNumber is the work request number padded to 8 digits. For example, a branch for a WR 654321 would be named "dev/f00654321".  The use of the "/" in the branch name will represent all features sharing the same "dev" segment as a single, collapsable directory in Visual Studio. Segments should follow the same rules that the names of variables usually follow—hence the "f" before the work request number in "dev/f00654321". (However, dashes are fine.) The WR number is padded so that feature branches can continue to be easily sorted chronologically. If WR numbers surpass 99999999 (and we aren't pruning with a valid reason or if we have some tasks < 99999999 that aren't to be pruned yet), then we could change the convention to dev/fe and use numbers with 10 characters of padding to preserve the sort. (We could theoretically continue this type of pattern until we spell "feature".) Branch names should contain only lowercase characters. Windows is not case-sensitive, but Git was developed on Linux and is case sensitive. An optional feature description segment may be added after the paddedWrNumber segment. For example: "dev/f00654321/my-feature"  WARNING: if a branch named "segment" already exists, you cannot create a branch named "segment/thing"    

Resolution Branches

• Resolution branches are branches designated to resolve conflicts between two feature branches if conflicts occur.
• We will use the convention "dev/f{feature1}-f{feature2}", where feature1 is the padded WR number for the "heavier"/"more-difficult-to-change" feature and feature2 is the padded WR number for the "lighter"/"easier-to-change" feature. For example, the name of a resolution branch between a WR 654321 and a WR 765432 would look like: "dev/f00654321-f00765432"

Release Branches

• Release branches are created for each release. This makes it very easy to 'rollback'. We just checkout a previous release branch and deploy code from that branch.
• We will use the convention "prod/v{versionNumber}". For a version number of '1.3.0', the branch name would be "prod/v1.3.0".

Bugfix Branches

• Bugfixes are fixes to released code that are not high-priority and can be released in the next scheduled release.  As such, bugfixes follow the same workflow that features use, with the only difference being the branch name.  
• The bugfix branch name convention is "dev/b{paddedBugNumber}", where paddedBugNumber is the TFS bug number padded in the same manner that feature WR numbers are padded. For example, a bugfix for a bug with the number 987654 on TFS would be: "dev/b00987654"

Hotfix Branches

• Hotfixes are fixes to released code that are high-priority and must be released immediately.
• Since we have not yet formally defined an single hotfix approach and proposed three different processes, the name convention will not be specified until a single hotfix approach is define. Refer to "Hotfix" section for the three potential hotfix workflows for implicit naming conventions.

A Note on Appropriate Cherry-Picking

If someone hands you an ice cream sundae where the banana is rotten and the ice cream was made from spoiled milk but the cherry on top was fresh and could be enjoyed on its own, you might pick the cherry out of the bowl and toss the rest.

If you started work on a branch and stopped because the changes were no longer needed, or a better solution was designed, but you did make a change that still could be useful on its own, you might cherry-pick the change from the branch and toss the rest of the changes.

Cherry-picks shouldn't really be used in-place of merging, since the changes lose the parent commit reference and cherry-picks can end up being applied out of order and really turn the release process into a nice nightmare.

Long-Lived Feature Branches

For now, we'll just advise merging changes from master once it is updated, and rebasing the long-lived feature branch changes on top of the changes in the master branch. Note that this approach means if multiple developers were working on the feature branch, then they would have to update their local branches to match the rebased feature branch.

This article may additionally be of assistance if the same merge conflicts arise for very-long-lived feature branches:
https://hackernoon.com/fix-conflicts-only-once-with-git-rerere-7d116b2cec67

Understanding Git Internals

For the curious, in order to get a good understanding of how Git works, you will need to know what a cryptographic hash function is and then what a Merkle tree is (this may also require a small amount of graph theory to understand the terminology often used, as well). Other knowledge of cryptography give insights into the system—knowing what a commitment scheme is will give intuition as to why we call changesets 'commits'.

Some resources in no particular order:

• https://yurichev.com/blog/git/
• https://www.chromium.org/developers/fast-intro-to-git-internals
• https://www.linkedin.com/pulse/git-internals-how-works-kaushik-rangadurai
• http://eagain.net/articles/git-for-computer-scientists/
• https://jwiegley.github.io/git-from-the-bottom-up/

If somewhat familiar with NodeJS, here's a bonus, well-commented JS implementation of Git:
http://gitlet.maryrosecook.com/docs/gitlet.html

Micro-Blog-Update

As one may have surmised, this blog is being neglected. There is good reason for this. I'm working on a few really interesting projects in my spare time instead of writing posts. Eventually, the projects I am working on will find their way onto this blog.

First off: please read the docs. In the official documentation, not only do we gain information of how Solidity is intended to work—we also can intuit the rationalizations for many of the design decisions; this intuition is invaluable as it allows us to determine what measures need to be taken in drafting up robust contracts, especially as when we later introduce complexity and shirk away from Solidity's safety mechanisms^[1]. It can only help to absorb the documentation.

Now, the core topic!

ABI (Part I)

An 'Application Binary Interface' (ABI) is the bridge between the application code (the higher level code us smart programmers may write) and the lower level, binary code that gets processed by dumb computers.

In the context of Ethereum, an ABI is how we are able to interact with smart contracts once they are put onto the Ethereum network. Remember, while we may write contracts in Solidity, we compile (specifically, using solc—the SOLidity Compiler) the Solidity code we write into bytecode. This is because the Ethereum Virtual Machine (EVM) cannot run Solidity—it knows nothing about Solidity. The EVM only knows opcodes (those things defined in Appendix H of the yellow paper). Solidity is just an abstraction^[2].

The official documentation states the reason for ABIs (with 'encoding' referring to bytecode): "The encoding is not self describing and thus requires a schema in order to decode". (You may also want to note that in the next paragraph, the documentation goes on to say, "No introspection mechanism will be provided.")

So, what this is telling us is that the bytecode for a contract is not something that we can look at and use to figure out how we are to interact with the contract. An ABI is the schema of which they are referring to. Note that an ABI is not actually part of the Ethereum protocol—you can write bytecode without an Application Binary Interface (or with an ABI of your own definition). While there is no ABI defined as part of the Ethereum protocol, there is a standard ABI used by seemingly everyone that is just a conventional bridge between Solidity (as well as the other popular higher level languages) and bytecode.

"Why isn't the encoding (bytecode) self describing?" you may ask. The reason that we require a separate schema to assist us in interactions with the encoding is that the Ethereum Virtual Machine is an abstraction (only the essentials) of the operations a processor would typically perform when given machine code. This process is similar to Java and the Java Virtual Machine. Different processors and hardware have different instruction sets, so the abstraction is necessary if we want some arbitrary code to run across multiple machines of varying hardware: programmers code in a higher level language that compiles into bytecode, and that bytecode is translated into the proper machine language for a particular machine—with this scheme, it allows the programmers to focus on the rules for their systems without having to worry about whether it will run on Windows, or Linux, or MacOS, etc.

When a Solidity contract is compiled, all the variable names, function names—even the contract name—are excluded from the resulting bytecode. The resulting bytecode is merely the opcodes the EVM needs, and nothing more. The variable names and all that stuff were actually just helpful tools and symbols to aide the development process. This information useful for development isn't contained in the bytecode; thus, the need for a separate schema—the need to keep separate lists of properties, functions, and events that our contracts have—the need for an ABI.

Function Signatures

But, even with the a list of all the properties and functions, how will we interact with them on a contract that lives on the Ethereum network? Well, before we answer that, let's simplify. One of things that Solidity does is that it makes functions for the properties that are declared public (interactable)—these functions simply return the value of the property. The mechanism that is used to interact with properties becomes the mechanism that is used for interacting with functions—only one mechanism is needed.

Now, how does the mechanism work? The mechanism is surprisingly simple, and we'll walk through our own design process of sorts to understand the concerns. Let us articulate what require: a manner to call a specific 'function' that exists in bytecode. We would need some kind of unique identifier for each function—what we need is called a 'function signature'.

A simple way, if you and I were to have designed it, might be to use the function or property names in the bytecode. An example function we might be wanting to invoke could be exampleFunction(), a made up function for demonstration purposes that'll take some int and do something with it. We might just design our EVM code to work with labels directly, so somewhere in the EVM could there might be exampleFunction, and based on some input, we would jump (go to) the label relevant to the input.

But, what would we do in the case of overloaded functions (multiple functions with the same name, but accepting different arguments)? Well, then we would have to include the parameters (arguments) into the identifier that would be included in the bytecode. So, for two example functions sharing the same name, we might have exampleFunction(int thing) and exampleFunction(int thing1, int thing2) (ignore the illegal characters for now).

There's a couple of concerns with this approach, though. The first is, for functions with a lot of parameters, the function signatures could get very long, and start to take up additional storage to fully encode—remember that blockchain storage is expensive, whatever data is put in the chain that will stay there for as long as the community carries on the project, and judging by the fact that [EXPLETIVE] FidoNet still lives, that'll be pretty much forever (or until the sun blows up and kills us all). The point is, it's expensive, so we need to look for parsimonious ways to shorten it up and keep it still unique to the function we intend to call. One easy way is by omitting any spaces. Let's do that. It's also good to make a rule like this just for consistency.

Now, another thing is that we don't actually need for function signatures are the names of the parameters since those are only used in the function body (that is, used by the code in the function), so having just the types of the parameters will suffice. But, we have an important consideration: the types we have chosen for our example are int, which is really an another name for int256. We'll have to change that to get rid of any potential ambiguity (among programmers with experiences in other languages, 32-bit integers are typically the default so 256-bit integers by default might be unexpected or even seem a little insane)—let's be explicit and consistent.

So, with all these considerations, this is where we have ended up:
exampleFunction(int256)
exampleFunction(int256,int256)

Hmmm . . . We end up with things of varying lengths, and they still can get pretty lengthy if they have many parameters. :/ Now, these are the core signatures of the functions that we will want to interact with, but remember—this is a cryptosystem—we haven't been thinking with fancy cryptographic tools in mind.

Omitted from the first Solidity/Blockchain post entirely was the concept of 'hashing'. We will define hashing as a means of fingerprinting a chunk of data—it is a process usually used to come up with unique identifiers for some files so that people can check if there have been any changes to the files since they were initially 'hashed'. 'Hashing algorithms' are the means of doing this, with the result being a 'hash code' (or 'hash' for short; 'hash' is used as a verb, too), which is a numerical value and as such can be represented in decimal (0–9), hexadecimal (0–F), etc. There are many different hashing algorithms around, and Ethereum largely uses the algorithm that was the leading candidate for becoming the latest 'Secure Hash Algorithm' when it was developed. That algorithm was originally used within Ethereum as SHA3, but unfortunately it didn't become the standard, so now we all try to call it by its proper name, Keccak-256. (The 256 means the resulting hash code is 256 bits, or 32 bytes, in size.)

With hashing now in mind, the last step is to put the function signature through the Keccak-256 algorithm, and then we'll get a unique fingerprint of the function signature of a standard length. Now, smart contracts will probably not have so many functions and properties where we need a 32 byte number—the max value for a 256-bit unsigned integer is:

115,792,089,237,316,195,423,570,985,008,687,907,853,269,984,665,640,564,039,457,584,007,913,129,639,935

That's two to the two-hundred-fifty-sixth power minus one (2**256 - 1). We're probably not going to have that many functions, so we can just shorten the resulting hash code. How about just four bytes (or 32 bits)? That gives us 2,147,483,647 as the max value. A bit more reasonable; it's a number we can at least say. Remember from the first section that a byte can be represented with two hexadecimal characters, so we end up with an number representable in eight characters, which is fairly tolerable (and doesn't contain any illegal characters).

So, a summary of what our process will be: format with functionName and parameter types (unaliased,no-spaces). This is what would be called the function signature. Then hash the function signature (using the Keccak-256 hash algorithm), and take the first 4 bytes of the resulting hash. That number—that is what we could put in our bytecode that'll run on the EVM. Well, actually, this is exactly what solc does for our Solidity smart contract properties and functions! Know that the resulting number should be called the MethodID, but note that it is often also referred to as the function signature, just to make things more confusing. (Here's a Stack Exchange that shows some pseudo-EVM code so you can sort of see what it looks like in action.)

solc uses this approach when compiling the Solidity contract into bytecode, so if we use that same approach when wanting to interact with the contract, we'll come up with the same MethodID that exists in the bytecode, and should be able to invoke the desired function.

ABI (Part II)

We've digressed from discussing the actual ABI, though. Remember, what the ABI is is just the core, essential information that is needed to bridge from the application level to the bytecode level, such as what is needed in order to do the above steps to get the encoding for a function (the compiler does this when compiling the contract, and we'll use it when calling functions on our deployed contract). The conventional ABI is essentially just JSON.

For example, here is our finished contract from the Solidity introduction:

contract ExampleContract {
    address public owner;

    function ExampleContract() {
        owner = msg.sender;
    }

    function isOwner(address _account) public constant returns (bool) {
        bool isOwner = (owner == _account);
        return isOwner;
    }

    function changeOwner(address _newOwner) public {
        if (isOwner(msg.sender)) {
            owner = _newOwner;
        }
    }
} 

Now, here is the ABI that gets generated when compiling the above contract:

[{
    "constant": true,
    "inputs": [{
        "name": "_account",
        "type": "address" }],
    "name": "isOwner",
    "outputs": [{
        "name": "",
        "type": "bool" }],
    "payable": false,
    "type": "function"
},{
    "constant": true,
    "inputs": [],
    "name": "owner",
    "outputs": [{
        "name": "",
        "type": "address" }],
    "payable": false,
    "type": "function"
},{
    "constant": false,
    "inputs": [{
        "name": "_newOwner",
        "type": "address" }],
    "name": "changeOwner",
    "outputs": [],
    "payable": false,
    "type": "function"
},{
    "inputs": [],
    "payable": false,
    "type": "constructor"
}]

The resulting ABI looks a little bit longer that the contract. This is because of the formatting and that our contract's method bodies are really short. More complicated contracts would likely have ABIs that are significantly shorter than the actual Solidity contract code.

Bonus

Let's go back to the docs: remember that the documentation said, "No introspection mechanism will be provided"? A pity. I don't know about you, but I'm pretty disorganized at times. I might misplace my ABI after deploying a contract.

We'll just have to make our own introspection mechanism, I guess. This is an unfinalized idea.

This is how it'll work (this is an abstract base):

contract IQueryable {
    function getABI() constant returns (string);
    function getParentTypes() constant returns (string);
}

• It could either be a contract or an interface at this point.
• getABI() (or potentially getAbi(), depending on a decision of what the style will be) is intended to return the ABI of a contract as a string with minified whitespace.
• getParentTypes() is intended to return a comma delimited list of all the types that the contract implementing the interface derives from. It is not intended to be recursive (one could define such a method either on the contract or make the contract implement an additional interface for this and either getABI() or getParentTypes() would allow it to be discovered).

All contracts I write will have to (some currently do) implement this interface. Right now it suffices to copy and paste the ABI after initially compiling a contract and compile it again. Eventually this will be automated with a special tool, but my efforts are prioritized and am I working on planning something else at the moment. The special tool will be implemented with a finalized IQueryable interface once other similar features are designed.

Conclusion

In this post, we've explored Application Binary Interfaces and got a good grasp on how solc turns function signatures into the MethodIDs that are encoded in the bytecode that the EVM plays with. With this information, we'll be able to do some interesting things later on, but at this point, we're just getting acquainted with the basics of all this crazy programmable-blockchain stuff.

Next week is either a continuation of this type of beginner, non-programmer track, or the beginning of a more advanced track on higher-level design decisions.

1. There will be a later post describing these, so don't worry if you don't yet know what is meant by 'safety mechanisms'—it suffices to say for now that there are restrictions for good reasons. ↩︎
2. As an aside, all Solidity really does is give us, programmers, convenient and relatively-safe, readable patterns of opcodes—patterns that are designed to be defensive. If you don't like the patterns or they don't fit your use case, you are free to build your own language that compiles into bytecode, but that really isn't necessary, because Solidity gives you the ability to write 'assembly' (work directly with those opcodes and the memory on the stack in either a somewhat human readable manner or instructional manner) within contracts. This, I'd argue, is the most powerful part of Solidity: in it, you can tell Solidity to go [EXPLETIVE] right off with its safety and staticity, and do some wicked cool [EXPLETIVE] when you need to. ↩︎

Well, that's a lot of words. What the heck is a smart contract? What's this Ethereum Virtual Machine (EVM)? To answer, we're gonna need a lot more words.

Here's a bit of a summary of how this all came about . . . (You may skip this if you already know some blockchain history and fundamentals.)

A Blockchain 101 of Sorts

A lot of geeks and nerds had been trying to make digital versions of paper money since the nineties. What's digital money—what were they trying to make? To understand, note that real life paper money has this property that you can hold all of your money in a wallet and when you make a purchase, you give someone some of the money from the wallet. This is fundamentally different from how those plastic card transactions work. Those work by giving a card number to the vendor, and trusting that the vendor takes the appropriate amount out of your account, with your bank as the intermediary that you also trust. It is equivalent to giving the vendor your wallet and hoping to get it back with all the contents you were supposed to. When using a card, the vendor could take out more than they said they would, or sell your card information—and another entirely different concern with this whole system is your bank could be hacked or be doing shady stuff. The dream of digital cash was that it would function like paper money—you give the money to the vendor, and they don't get access to your wallet or bank account.

There were a few systems proposed and implemented to try to enable digital (remote, at a distance) transactions analogous to paper money where the recipient doesn't have to be trusted as they don't get access to an owner's funds, but these systems shared a commonality in that they still required a third party to either manage balances or authenticate transactions. In short, the digital cash thus far still required a digital bank—a third party that had to be trusted.

In 2008, an anonymous dude with a fake name — possibly a neighbor's ;) — came along and proposed (and implemented in 2009) a version of digital cash that did not require a digital bank. This is Bitcoin.

Bitcoin in Brief

Bitcoin is actually a fairly simple system, conceptually. I'll refer you to the whitepaper. If you already know how all those internet pirates manage to thwart all the big movie companies, then Bitcoin is readily understandable to you. Bitcoin manages to avoid reliance on a trusted third party because it is peer-to-peer. The way that internet piracy works, where all the little pirates all keep files of music, movies, and television shows and broadcast them to eachother, is the same way that Bitcoin works. Only, instead of some HBO show that they are distributing, it is a list of 'cash' balances.

But what are the accounts and balances in Bitcoin? Like most of the digital cash systems from the nineties, Bitcoin uses cryptography.

Public-key cryptography within Bitcoin is how the accounts are managed. You may think of it somewhat like a username and password. The public key is your 'username', and the private key is your 'password'. Now, typically in public-key cryptography (which is just the academic term for this type of system), you pick the 'password' (the private, secret key) first as the most random as possible number, and this private key is used to create the public key using some mathematical "trapdoor" function. (We may later on explore trapdoor functions for illustrative purposes with a simpler cryptosystem, RSA, in a future post.) Basically, with a trapdoor function, the produced public key is derived from the private key, but no one but the private key holder knows what the private key is.

Unlike your username/password account combination, you can use your private key to make other things that other people who only know your public key can verify was produced by someone in possession of your private key (which, if it was really random and you practiced good SecOps, would only be you). Using your private key to make something that only the private key can produce, is called 'signing', and the resulting 'thing' is called a 'digital signature'. Digital signatures take an input—typically called a message—and act on the message in a way that uses the private key to produce an output that can be verified as produced by the private key that produced the public key. A user wishing to 'send' or transact some bitcoin signs a standardized message with the transaction information, and if the signature and message are valid, all the little digital money pirates all update their records with the new balances.

Bitcoin has some other elements in the design for validation of transactions, using timestamps and a scheme called Proof-of-Work to protect against the Bitcoin network from attacks (lies about transactions and balances). A bunch of transactions are verified together in a 'block' (or batch), and then any new transactions get put in a new block. The new block says which block came before it, and this process goes on indefinitely. Because transactions can be grouped together differently (make different blocks), Bitcoin, according to its whitepaper, is considered to be the longest chain of blocks. This "longest-chain-IS-Bitcoin" principle rests on the assumption that the majority of the Bitcoin network is honest (not lying about transactions). Bitcoins are created from thin air only when a block is validated and given to the validator (validators that validate with Proof-of-Work are called 'miners').

Whew, that's quite a bit to explain, huh? Well, that's largely because Bitcoin is interdisciplinary. It draws from crytography, computer science, economics, and madness. There's plenty of other resources that go in depth and I advise you to seek them out. No particular recommendations from me here so you're forced to do your own research. ;) Onto the next thing!

Introducing Ethereum

Essentially, after Bitcoin's arrival, lots of other nerds started trying to make other things with Bitcoin. That is, just not using it for solely digital cash transactions, but for also representing ownership of real-world and other digital assets. After a few of these type of projects trying solve specific problems with Bitcoin popped up, some people noted the limitations of Bitcoin, as it was not designed for these things, and came up with a more general solution that could be used for virtually any purpose. This is Ethereum.

Ethereum shares many similarities with Bitcoin. Ethereum, too, has a whitepaper (eveything in this space does! Whole lotta reading!). Omitted from the above Bitcoin section for brevity are 'addresses'. Both Bitcoin and Ethereum share public-key cryptography as a core aspect, and both use the public keys to create another thing that is called an 'address'. Addresses are derived from the public key and are what are actually used to keep balances of bitcoin or ether. Transactions are from one address to another, but are only considered valid as long as they are digitally signed by the holder of the private key that is the pair to the public key of which the spending address is derived. That's a hard sentence to follow, I know. Here's a rephrasal: For some digital token at an address derived from some public key, it can only be 'spent' (transferred) to another address if the person who is trying spend the digital token proves that they know the private key that produced the public key.

While both are peer-to-peer networks using public-key cryptography to manage account-balances, Ethereum differs in that its transactions can also invoke code. Let me phrase that another way: Ethereum is programmable. Another way: The Ethereum network is essentially a world computer; this is the Ethereum Virtual Machine. Code can be put on the Ethereum network and triggered by accounts. Rules for whatever system is sought is put into code by programmers and then deployed to the network, where it is executed on the Ethereum Virtual Machine (EVM).

To accomplish this goal of a programmable, peer-to-peer platform, some other elements are part of the Ethereum's design, such as 'gas', a mechanism that prevents the possibility of code getting stuck running forever. Gas is an analogue to gas in the real world. You put gas in your car, and your car can drive until it runs out. In the real word, gas is used for the combustions in your car's engine, but in the Ethereum world, gas is used for each computational step in your code. Gas is supplied before the execution of some code. (It should be noted that there's a limit to the amount of gas that can be used in a transaction.) What happens when an interaction with a  contract runs out of gas is that any changes that might have been made are reverted.

If all this sounds crazy, that's because it is. :)

Smart Contracts

So, what the hell is a smart contract? Well, we're in the cryprocurrency world. These cryptosystems deal with digital token analogues to cash, and Ethereum provides a platform for programming rules for interactions with these digital representations. Other representations can be coded up, arbitrary data can be stored in and retrieved from the blockchain, and it's all initiated by accounts and requires some balance of 'Ether' to pay the gas for the transaction. Since the code on the Ethereum network deals with smart, programmed rules that are only executed by consenting parties (and is typically financial) and enforced by the EVM which runs the code, and since, in the legacy world, transactions made in accordance to written-out rules agreed to by two consenting parties enforced by law are called contracts, it made sense to call these things on the Ethereum network smart contracts. That, and Nick Szabo (whom I suspect ol' 9000 tried to trick the world into thinking was the most plausible candidate for SN) coined the term in '96.

That's the end of the history and fundamental concepts of all this stuff. Now we'll get ready to start thinking in terms of Contract-Oriented Programming!

Solidity

Solidity code is not the code that runs on the EVM.

Life without Solidity

The code for an arbitrary contract that runs on the EVM is in the form of bytecode, which is most commonly seen in hexadecimal representation.

Ah, that word, 'hexadecimal'. What does it mean? Well, what's 'decimal'? That's the numbering system you're probably most familiar with, where we use 10 characters (0–9) to represent values. When representing values larger than nine, we just use multiple characters from the same set. An example of this is '13', which if we were to represent in countable dots, would be •••••••••••••. In hexadecimal, we have more than 10 characters to represent values with. We have 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9 — all characters you are familiar with — but, we extend those characters with A, B, C, D, E, and F, making a total of 16 characters. When writing numbers in hexadecimal, it is convention to preface with 0x (it'd be too damn confusing otherwise). So, thirteen in hexadecimal can be written as 0xD or 0xd (casing does not matter in hexadecimal). (There is another representational system called binary that we'll explore in a section or post on the topic of Boolean logic.)

Now, a 'byte' is any two hexadecimal characters. A 'nibble' is half a byte, or just one hexadecimal character. Bytecode is just a bunch of bytes, and it typically looks like this:

0x42B7E6190000000000000000000000000000000000000000000000000000000000000539000000000000000000000000000000000000000000000000000000000000E298

(This is just a contrived example of what bytecode looks like in general—bytecode for full, sophisticated contracts is much longer; this example doubles to subtly set the stage for a explanation/tutorial much later on for crafting raw transactions where it will be explained that the function signature is the first four bytes, and any arguments to functions are padded to 32 bytes in total. You can ignore this comment, I'm not sure why I'm including it as it just makes this more difficult to follow . . . ¯\_(ツ)_/¯ )

The bytecode that runs on the EVM corresponds to the EVM opcodes. Scroll down and take a look at Appendix H of the Ethereum yellow paper. You see how incomprehensible that is? Yeah, it's almost just as incomprehensible to programmers too, which is why it is very rare to write bytecode directly. Ethereum developers use higher-level programming languages that compile into bytecode that conforms to those specifications.

NOTE: Solidity is the most popular language for  these days, but there are others: Viper, Serpent, Mutan, and LLL.

Life With Solidity

With Solidity, it is possible to write code for smart contracts that looks like this:

contract ExampleContract {
    string public owner;

    function ExampleContract() {
        owner = "Rick Sanchez";
    }
}

One immediate thing to observe is that this is more readable than however it would appear in bytecode. This code is simple: it is a definition of a contract named 'ExampleContract', and when this contract is deployed to the Ethereum network, it sets its 'owner' property to 'Rick Sanchez'. Anyone could then, as long as they have the interface to this contract, ask it who its 'owner' is, and find out that it is 'Rick Sanchez'.

Let's add to this contract definition a little bit, since Solidity is a programming language. For demonstration purposes, let's say we want to make this contract work in a way that the current owner of the contract can change who the owner is. Let's first extend the contract so that we can give the contract a name and it tells us if the name is the name of it's owner (that way we don't have to check ourselves).

contract ExampleContract {
    string public owner;

    function ExampleContract() {
        owner = "Rick Sanchez";
    }

    function isOwner(string _name) public constant returns (bool) {
        bool isOwner = (owner == _name);
        return isOwner;
    }
}

NOTE: There're much more concise ways to write this in Solidity, and this isn't yet a good example of a way to actually maintain ownership of a contract. This is to first show the language in digestible pieces. We are showing the features of the language before articulating them.

So, what we have done is create a function named isOwner() that takes in a string of characters, performs an equality check between the passed in name and the contract's owner, and returns the result. Pretty simple. Terminology: if we want to use a function that a contract provides, we 'call' or 'invoke' or 'execute' it (all synonyms, though 'call' has a special meaning in Ethereum that we'll clarify later).

Now, how might we change the owner of the contract?

contract ExampleContract {
    string public owner;

    function ExampleContract() {
        owner = "Rick Sanchez";
    }

    function isOwner(string _name) public constant returns (bool) {
        bool isOwner = (owner == _name);
        return isOwner;
    }

    function changeOwner(string _newOwner) public {
        owner = _newOwner;
    }
}

Well, now we've added a new function. This latest addition is aptly named changeOwner(). When called, the contract takes in a new string and changes its 'owner' property to the new string's value.

But, now we may have introduced unintentional behavior! It is also here that I propose the term that should be used for these unintended behaviors and exploitable behaviors: loopholes. We have a loophole in our contract. (In normal programming, it is conventional to call these 'bugs', even though bugs should really only refer to those strange circumstances where your code isn't working when it should and it turns out there was a literal bug crawling around in your computer.)

The loophole in this contract is that anyone can call this function on our deployed contract and change its owner. We'll want some way to check if the person that wants to change it is the current owner, and let them change it when they are. If not, we'll simply just not do anything.

But before we try coding it up, let's note that we still have to determine a way to ensure that whoever is calling the contract is the current owner. Right now, all we have is a string of the owner's name—and that's it. Alright, let's continue with this bad ownership contract.

contract ExampleContract {
    string public owner;

    function ExampleContract() {
        owner = "Rick Sanchez";
    }

    function isOwner(string _name) public constant returns (bool) {
        bool isOwner = (owner == _name);
        return isOwner;
    }

    function changeOwner(string _yourName, string _newOwner) public {
        if (isOwner(_yourName)) {
            owner = _newOwner;
        }
    }
}

Now, we've modified the contract's changeOwner() method ('method' is fancy term for 'function' I'll slip into on occasion). The new method  takes in two strings, the first is intended to be the name of the person requesting the change in ownership, and the second being the new owner. The new function even uses another function of the contract! This is almost what we want for the final solution, except the loophole here is anyone could ask the contract what the current owner's name is first, then call the function and provide the current owner's name and a new owner, and the contract's owner would be changed.

We just aren't thinking with cryptography in mind yet! Remember, this is a cryptosystem! To review some of the stuff in the earlier Blockchain 101 sub-sections, recall that transactions are messages signed by someone in possession of the private key that is the pair to the public key that is known. And recall that the token, or ether, is transferred from one address to another. Now I'll tell you something maybe new to you: all the transaction information for the current interaction with a contract is actually available to us in Solidity as global variables.

Variables, Types, and Scopes

What's a global variable? First, let's just cover variables.

If you've ever had an algebra math class, then you actually know the term 'variable'. In programming, we use that term, and it has the same meaning. You might notice, remembering back to your algebra days, that the term function was also used. It has roughly the same meaning in programming, and this is more apparent if we look at a mathematical example. (Remember that 'integers' are negative and positive whole numbers.)

NOTE: If you've never had an algebra course, you're likely in over your head here, and should go watch some KhanAcademy videos and come back. In a pinch, I guess it'd suffice to say a 'variable is something that can vary in value'.

Here's a function that adds 2 to whatever value it is given:

function f(int x) public returns (int) {
    return (x + 2);
}

As a mathematical function, it would be written as f(x) = x + 2. The above code is written with Solidity's syntax, but note that it would have to be inside a contract definition to be runable. Let's note some of the differences between the Solidity code and the formula. The code has more information than the formula. The formula only deals with one type, 'numbers' (and it never specifies the type, because, as a math formula, we can assume that 'x' is a number). Solidity has multiple types, with two you've seen now being strings and integers. Solidity is a compiled language; it compiles into bytecode. With compiled languages that support multiple types, it is common to have to specify the type for each variable and returned value so that the compiler (in our case, the program that converts Solidity-code into bytecode) knows how other variables and operators (like the + symbol)  are supposed to interact with eachother.

Now that we have 'variable' pinned down, what's the 'global' part in 'global variable' mean? Well, in programming, there is often the concept of 'scope'. Typically, we have a local scope and a global scope. The local scope is where variables inside blocks of code (such as inside a function—blocks of code are denoted with curly braces, with the opening '{' being the start of a block and the closing '}' being the end) have values and meanings that other variables in the scope can access, but these values are not accessible from the global scope. The variables in the global scope are visible inside the local scope.

Here's a concrete example, as I'm afraid that it's too abstract to follow otherwise. NOTE: These examples are syntactically similar to Solidity for simplicity, but not actually 'Solidity'.

int x = 12;

function example(int y) public returns (int) {
    return x + y;
}

function secondExample(int z) public returns (int) {
    // This function produces an error
    return y + z;
}

So, in the first example() function, the local variable is y and the global variable is x. This function simply adds whatever number y is to x, which happens to be 12. The code for this function is free of errors.

The secondExample() has an error, and that is that it as attempting to use a y variable, possibly because the programer of it was thinking of the first function. This code would not compile. No variable y has been defined in the secondExample() function. If a y variable were defined in the function, then everything would be a'ight:

function thirdExample(int z) public returns (int) {
    int y = 19;
    return y + z;
}

Note that we can use the same variable name inside different functions. We can even use the same name as a global variable inside our local scope, but note that we would no longer be able to access the global variable. This is called 'shadowing'.

int q = 23;

function shadowExample(int w) public returns (int) {
    var q = 27;
    return w + q;
}

Now 'var' is a special keyword that will be explained later, but it is used to tell the compiler, "Ayy, I'm fine with whatever type you're gonna make this variable." In some cases, the compiler can infer the type of a variable.

In the above shadowExample() function, the returned, resulting value is whatever value is given as the parameter plus 27. The global q variable is shadowed, but this does not change the value of the global q variable for other functions that might be using it. Shadowing is generally best avoided.

Global Variables

There's a list of global variables for you to leaf through in the official Solidity documentation, but the one that you absolutely must know is msg.sender. This global msg variable is accessible at any point in Solidity contract definitions (unless you shadow it) and its sender property is almost always the address of whoever directly initiated the current, most recent interaction with the contract. These global variables are not Solidity-specific, as they are specified in that nasty yellow paper.

With msg.sender, we can fix our 'ExampleContract' to keep track of its owner in a better way. We no longer will be using a string of the owner's name for keeping track of ownership. Remember, every interaction is caused by a transaction, and every transaction is between two addresses and initiated by one party in possession of a secret key, and that no one else can "pretend" to know the private key, and that Solidity can access the address of who initiated the transaction.

With all that in mind (yes, it is a lot—it is recommended to read it over and over again, starting from the beginning as necessary, until it is understood and internalized), here is an improved 'ExampleContract':

contract ExampleContract {
    address public owner;

    function ExampleContract() {
        owner = msg.sender;
    }

    function isOwner(address _account) public constant returns (bool) {
        bool isOwner = (owner == _account);
        return isOwner;
    }

    function changeOwner(address _newOwner) public {
        if (isOwner(msg.sender)) {
            owner = _newOwner;
        }
    }
} 

The immediate difference that should be noticeable is the replacement of the string type with the address type. All the functions of this contract have been modified in some form or another.

When a Solidity contract is deployed to the Ethereum network, any function (but there can only be one) bearing the same name as the contract is automatically executed. This is called the 'constructor'. In the constructor for our new 'ContractExample', we are setting the contract's 'owner' property to be the address of whoever created the contract. We could alternatively hard-code an address:

function ExampleContract() {
    owner = 0xE16bD51697Ec9987952696D0D6Ef3761fE08DADd;
}

But, we can do this better:

function ExampleContract(address _firstOwner) {
    owner = _firstOwner;
}

Constructors can be given parameters like any function, so we can make contracts that have initial states that can vary without having to write different contracts with each initial values that we want the different instances to have. This was also an excuse to put in an address I own in case anyone wants to leave me a fat tip ;).

Another difference between this version of the 'ExampleContract' and the one prior to it is the that changeOwner() is now back to only one parameter, as we don't have to trust that people are telling us their real names now that we're doing ownership based on addresses and because transactions can only be initiated by someone in possession of the private key that is the pair to the public key corresponding to the sending address.

Conclusion

In this post, we cursorily covered the history of blockchains, provided a summary of smart contracts, and saw what Solidity looks like, why it's useful, and even started to understand some of the features of the language.

I suppose I've written way too many words, but hopefully some of them have clarified some things or introduced you to new things. There's plenty of resources out there documenting many of these things better than I can do, but if you have found some good resources that you'd like to share, please leave them below for others to see.

Tune in sometime soon for more Ethereum and Solidity bloggin'. I think the next post will be about contract interfaces, and it'll include an idea to make things a lil' easier.

Who This Blog Is For

This blog is really only for myself (all blogs are for their bloggers, but few bloggers will make that admission). It may additionally be of interest for programmers (professionals and hobbyists), aspiring programmers, and possibly those wanting to stay up to date on some of the cool technological happenings of our time. I usually try to explain everything I do, and I like to think that I give good intuitions, so this blog will, I hope, be of use to those wanting to learn and understand some stuff.

About Me

Somehow in this crazy, spinnin' world, I ended up a developer, which surprises me because I always thought I was going to end up a homeless feller (although, to some, there is no distinction betwixt the two).

NOTE: The rest of this section grazes over a bunch of words that have no meaning to non-developers, and is not intended to be instructive in any way.

My first programming language was, regrettably, ActionScript. I know, right? The reason was that I played with Macromedia tools (wanting to hone some animation skills to participate in the fan-revival of one of my favorite cartoons) when I was 12 and joined a Clock-Crew-derivative Flash animation group. I have no shame, which is why I'm explaining all this. Well, I have some shame, as I'm not going to specify which group.

Using Flash, I stumbled into ActionScript and found myself trying to make games. Fast forward a few years (skipping some time I spent dedicated wholly to musical instruments), and I was making websites (logos, art, HTML, CSS, a teeny bit of JS, and very rarely some PHP) in order to pay for college housing and scammy fees. I majored and graduated in some hybrid arts and computers abomination program and took C++, Java, Ruby, Objective-C, and C# courses. (I play with Node and Python on occasion.)

Now, I've been doing Rails projects for quite a while (worked as the sole developer for a Bitcoin startup in 2013–2014), though my day job these days is doing .NET MVC stuff. (To keep myself from becoming too bored, I like to leverage all the cool fancy C# features (but sometimes resorting to hacking up CIL) to make awesome tools in keeping with the Ruby paradigm of ease for the programmer.)

What I'm currently interested in (code-wise) these days seems to be Ethereum. I've become fairly proficient in Solidity, as I've got a few projects in mind, so expect some blog posts with some cool patterns and solutions.

Cracking the Blog Code

This is something like the eighth blog I've started in the past ten years. Typically, and I imagine this is common, I start up a blog, do one post and forget about it or lose interest. Well, no more! (I hope.) I suspect the trick to getting into the habit of regular blogging (which, like all things, should never be done for the sake of itself) is to declare in advance the next post topic and date so that there is a deadline.

Tune in next week (possibly) for the first real post: Introduction to Solidity for Non-Programmers!