DEV Community: C.OG

Solana teardown: Walkthrough of the example helloworld program

C.OG — Fri, 22 Oct 2021 14:34:39 +0000

In this article, we'll walk through the helloworld Rust program line-by-line and begin to unpack how programs on Solana work.

Who this article is for

This walkthrough assumes that you've written code in any programming language or have a basic understanding of Rust. You don't need prior experience writing programs (smart contracts) on Solana or any other blockchain. I won't spend much time explaining the Rust specific code or idioms but rather focus on the Solana program.

Let's get started.

Use declaration

use borsh::{BorshDeserialize, BorshSerialize};
use solana_program::{
    account_info::{next_account_info, AccountInfo},
    entrypoint,
    entrypoint::ProgramResult,
    msg,
    program_error::ProgramError,
    pubkey::Pubkey,
};

We bring libraries and traits into scope with the use declaration. It allows us to bind a full path to a new name for easier access.

Greeting Account

#[derive(BorshSerialize, BorshDeserialize, Debug)]
pub struct GreetingAccount {
    /// number of greetings
    pub counter: u32,
}

Programs are stateless. If you need to store state between transactions, you can do so using Accounts. In Solana, EVERYTHING is an account. The Solana blockchain only sees a list of accounts of varying sizes. If an account is marked "executable" in its metadata, then it is considered a program. We'll talk more on accounts later, but for now, the understanding we need is that; our Greeting Account can hold data, and this data is in the shape of our GreetingAccount struct. Our accounts data property will have a counter property which we'll use to store a count of all the greetings. This data will persist beyond the lifetime of our program.

Entrypoint

entrypoint!(process_instruction);

We register the process_instruction as the entrypoint symbol which the Solana runtime looks up and calls when invoking the program.

process_instruction

pub fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    _instruction_data: &[u8],
) -> ProgramResult {
// --snip--

All programs have the same signature. Let's take an in-depth look at the parameters.

program_id

The program_id is the public key (the address) of the currently executing program. In our case, this will be the public key of our HelloWorld program.

accounts

Accounts really deserve their own post. For now, I'll keep it brief. The accounts is an ordered list of the needed accounts for this transaction. The only properties that an account owner can modify are lamports and data.

instruction_data

The _instruction_data is specific to the program and is usually used to specify what operations the program should perform. In this helloworld example, we only have one instruction, "greet", so the instruction_data is unused, hence the preceding _. That's a Rust idiom to keep the compiler happy.

Logging

msg!("Hello World Rust program entrypoint");

We can output logs from our program using the msg! macro. The caution here is that these messages are visible by viewing the program logs on the solana explorer.

Accounts

let accounts_iter = &mut accounts.iter();
let account = next_account_info(accounts_iter)?;

We take the list of accounts we received via our entrypoint and convert it into an iterable that we can iterate over. The Solana program library provides the next_account_info function that returns the next account in the list.

It's important to note that programming in Solana requires you to think about your "data model" or "program model", as it were. Since we have to specify all the accounts a transaction will need, we need to think about; what accounts our program needs, the purpose of the account, and the relationships between them. For example, when transferring lamports, an instruction may define the first account as the source and the second as the destination.

The instructions our program can perform are essentially the API of our program. Therefore, we must know how to call these APIs and what order we need to provide the accounts. We specify this in an instructions.rs file. An example of this can be found in the token program.

Validation and Security

if account.owner != program_id {
    msg!("Greeted account does not have the correct program id");
    return Err(ProgramError::IncorrectProgramId);
}

It's always good practice to validate the accounts you receive and assert that they have the correct permissions and are the accounts you are expecting.

Since our program needs to modify the data property, we need to check that the program is the owner of the account we are about to change. If not, we error out of the program.

Have a look at programs written in the Solana Program Library. You'll always find an exhaustive list of checks validating the inputs to the program.

Serialization / Deserialization

let mut greeting_account = GreetingAccount::try_from_slice(&account.data.borrow())?;
greeting_account.counter += 1;

Hidden in here are a lot of rust idioms, but we'll focus on the deserializing part.

In Solana, an account can store ANY binary data. The Solana blockchain doesn't know what that data is. It's the responsibility of the program or client to understand it. For you to store data, you incur a storage cost called rent. Rent is another pretty big topic, so we'll gloss over it for now and do an in-depth look when we do a teardown of the client app in a future post.

Back to the data. Each account can store its own type of data. In our case, the data we are storing is of type GreetingAccount. Since we store the data in binary, we need to deserialize it when reading it and serialize it when saving it.

Let's retake a look at our struct.

#[derive(BorshSerialize, BorshDeserialize, Debug)]
pub struct GreetingAccount {
    /// number of greetings
    pub counter: u32,
}

To increment the counter, we need to deserialize the binary data into a GreetingAccount. For this, we use the borsh library. Solana doesn't enforce how we serialize or deserialize our data, so the choice of library is up to us.

let mut greeting_account = GreetingAccount::try_from_slice(&account.data.borrow())?;

We take the binary data in account.data and try to deserialize it into a GreetingAccount. If that fails, we'll get an error.

You can read more on the .borrow() syntax from the official Solana docs.

greeting_account.counter += 1;

Once we have successfully deserialized the data, we can now increment the counter.

greeting_account.serialize(&mut &mut account.data.borrow_mut()[..])?;

We call the serialize method on the greeting_acocunt, which serializes the GreetingAccount struct and updates the data property.

msg!("Greeted {} time(s)!", greeting_account.counter);

Ok(())

We then log the new counter and return the result of our program to signal that this transaction was successful.

Resources

Footnotes

Thank you for the guidance, support and review of this article.

@therealchaseeb, @jamesflorentino and @fastfrank.

Follow me on twitter to read more about developing on Solana.

Solana: How to send custom instructions via instruction data

C.OG — Sat, 16 Oct 2021 15:16:52 +0000

In this article, we'll walk through the process of sending a custom instruction to a solana on-chain program. We'll modify the solana example helloworld to take two instructions, SayHello and SayGoodbye.

Here's a look at the final result:

Let's get started. Picking up from where the helloworld tutorial leaves us.

Define API of the program

// instruction.rs
#[derive(Debug)]
pub enum HelloInstruction {
    SayHello,
    SayBye,
}

We create an enum that will contain what operations our program is able to perform.

instruction.rs is responsible for decoding instruction_data.

Decode `instruction_data`

// instruction.rs
+use solana_program::{program_error::ProgramError};
+
#[derive(Debug)]
pub enum HelloInstruction {
    SayHello,
    SayBye,
}

+impl HelloInstruction {
+    pub fn unpack(input: &[u8]) -> Result<Self, ProgramError> {
+        let (&tag, rest) = input
+            .split_first()
+            .ok_or(ProgramError::InvalidInstructionData)?;
+
+        Ok(match tag {
+            0 => HelloInstruction::SayHello,
+            1 => HelloInstruction::SayBye,
+            _ => return Err(ProgramError::InvalidInstructionData),
+        })
+    }
+}

We create an associated function called unpack which takes the instruction_data and returns either a variant of the HelloInstruction or a ProgramError.

// --snip--
let (&tag, rest) = input
    .split_first()
    .ok_or(ProgramError::InvalidInstructionData)?;
// --snip--

We split the instruction_data slice and receive a tuple containing &tag which is the first element and rest which are the remaining bytes.

&tag (a number/u8 ranges; 0 - 255) is mapped 1:1 to an operation. This becomes clearer when we create the instruction on the client, more on that later on.

rest will have the remaining bytes that may contain additional information that the operation will need.

We transform the Option with .ok_or(ProgramError::InvalidInstructionData)?; into a Result, if the Option is of the None variant we return an InvalidInstructionData error. More on the ok_or method.

Ok(match tag {
    0 => HelloInstruction::SayHello,
    1 => HelloInstruction::SayBye,
    _ => return Err(ProgramError::InvalidInstructionData),
})

We can now match the tag to know what operation our program should run. We return an error if none of the known instructions are matched.

Update `process_instruction`

// lib.rs
// --snip--
+pub mod instruction;
+use crate::instruction::HelloInstruction;
// --snip--

pub fn process_instruction(
    program_id: &Pubkey, // Public key of the account the hello world program was loaded into
    accounts: &[AccountInfo], // The account to say hello to
    instruction_data: &[u8],
) -> ProgramResult {
    msg!("Hello World Rust program entrypoint");
+
+   let instruction = HelloInstruction::unpack(instruction_data)?;
+   msg!("Instruction: {:?}", instruction);

    // Iterating accounts is safer then indexing
    let accounts_iter = &mut accounts.iter();

    // Get the account to say hello to
    let account = next_account_info(accounts_iter)?;

    // The account must be owned by the program in order to modify its data
    if account.owner != program_id {
        msg!("Greeted account does not have the correct program id");
        return Err(ProgramError::IncorrectProgramId);
    }

    // Increment and store the number of times the account has been greeted
    let mut greeting_account = GreetingAccount::try_from_slice(&account.data.borrow())?;
    greeting_account.counter += 1;
    greeting_account.serialize(&mut &mut account.data.borrow_mut()[..])?;

    msg!("Greeted {} time(s)!", greeting_account.counter);

    Ok(())
}

We bring our HelloInstruction into scope with use crate::instruction::HelloInstruction; and attempt to decode the instruction with let instruction = HelloInstruction::unpack(instruction_data)?;

For now we'll just log the instruction. Later on we'll modify our code to use this instruction.

A quick recap of what we've done so far:

Defined our program API with the HelloInstruction enum
Unpacked (aka deserialize) our instruction_data byte array to retrieve the operation from our client
Logged the decoded instruction

Let's build and re-deploy our program. If you're unsure how to do this, take a look at the example helloworld docs. We can now run our client and see what our log message shows.

We get an error: Program log: Instruction Err(InvalidInstructionData) because our client is not passing a valid instruction. Let's fix that.

Update `sayHello`

// hello_world.ts
// --snip --

/**
 * Say hello
 */
export async function sayHello(): Promise<void> {
  console.log('Saying hello to', greetedPubkey.toBase58());
  const instruction = new TransactionInstruction({
    keys: [{pubkey: greetedPubkey, isSigner: false, isWritable: true}],
    programId,
-   data: Buffer.alloc(0),
+   data: createSayHelloInstructionData(),
  });
  await sendAndConfirmTransaction(
    connection,
    new Transaction().add(instruction),
    [payer],
  );
}

We replace the call to Buffer.alloc(0) with our new function createSayHelloInstructionData() which will return a Buffer.

Create `createSayHelloInstructionData`

For this we'll need to install two libraries.

npm i @solana/buffer-layout buffer

// hello_world.ts

import * as BufferLayout from '@solana/buffer-layout';
import { Buffer } from 'buffer';

// --snip--

function createSayHelloInstructionData(): Buffer {
  const dataLayout = BufferLayout.struct([
    BufferLayout.u8('instruction')
  ]);

  const data = Buffer.alloc(dataLayout.span);
  dataLayout.encode({
    instruction: 0
  }, data);

  return data;
}

We create a buffer layout structure with one field; instruction. This is where we'll encode what operation we want to run in our program, which is a u8.

const data = Buffer.alloc(dataLayout.span);

We then allocate a new buffer using the size from the buffer layout that we created earlier.

dataLayout.encode({
  instruction: 0
}, data);

Finally we encode the instruction (instruction: 0) into the buffer.

Th instruction: 0 corresponds to the tag variable that we get in the first element of the instruction_data slice.

// --snip--
let (&tag, rest) = input
    .split_first()
    .ok_or(ProgramError::InvalidInstructionData)?;

    Ok(match tag {
        0 => HelloInstruction::SayHello,
        1 => HelloInstruction::SayBye,

// --snip--

Now when we run our client, we see that our instruction has been decoded correctly.

We get the correct operation: Program log: Instruction Ok(SayHello).

Great! we're almost done. Have a go at creating the createSayByeInstructionData function. Which is identical to the createSayHelloInstructionData function except for the instruction that we need to send.

Now let's change our program to decrement the greeting counter when we received a SayBye operation.

Update `process_instruction`

pub fn process_instruction(
    program_id: &Pubkey, // Public key of the account the hello world program was loaded into
    accounts: &[AccountInfo], // The account to say hello to
    instruction_data: &[u8], // Ignored, all helloworld instructions are hellos
) -> ProgramResult {
    msg!("Hello World Rust program entrypoint");
    let instruction = HelloInstruction::unpack(instruction_data)?;
    msg!("Instruction {:?}", instruction);

    // Iterating accounts is safer then indexing
    let accounts_iter = &mut accounts.iter();

    // Get the account to say hello to
    let account = next_account_info(accounts_iter)?;

    // The account must be owned by the program in order to modify its data
    if account.owner != program_id {
        msg!("Greeted account does not have the correct program id");
        return Err(ProgramError::IncorrectProgramId);
    }

    // Increment and store the number of times the account has been greeted
    let mut greeting_account = GreetingAccount::try_from_slice(&account.data.borrow())?;
+
+   match instruction {
+       HelloInstruction::SayHello => {
            greeting_account.counter += 1;
+       },
+       HelloInstruction::SayBye => {
+           greeting_account.counter -= 1;
+       },
+       _ => {}
+   }
+
    greeting_account.serialize(&mut &mut account.data.borrow_mut()[..])?;

    msg!("Greeted {} time(s)!", greeting_account.counter);

    Ok(())
}

Now that we've made a change to our program. We need to build and deploy it again.

Let's run our client.

Running our client multiple times to show that our greeting count is being incremented.

Let's round this up by sending a SayBye operation.

// --snip--
export async function sayHello(): Promise<void> {
  console.log('Saying hello to', greetedPubkey.toBase58());
  const instruction = new TransactionInstruction({
    keys: [{pubkey: greetedPubkey, isSigner: false, isWritable: true}],
    programId,
-   data: createSayHelloInstructionData(),
+   data: createSayByeInstructionData(),
  });
  await sendAndConfirmTransaction(
    connection,
    new Transaction().add(instruction),
    [payer],
  );
}

function createSayByeInstructionData(): Buffer {
  const dataLayout = BufferLayout.struct([BufferLayout.u8('instruction')]);

  const data = Buffer.alloc(dataLayout.span);
  dataLayout.encode(
    {
      instruction: 1,
    },
    data,
  );

  return data;
}

We run our client again.

Our program correctly decodes the SayBye operation and decrements our greeting count.

Congratulations! We've managed to modify our program to specify what operation the program should perform.

Follow me on twitter to read more about developing on Solana.

VS Code Knowledge Pill: Profiles switching using Workspaces

C.OG — Sun, 10 Oct 2021 19:15:10 +0000

I've longed for a profile/settings switcher in VS Code that loads specific settings or extensions depending on a specific project or what programming language I'm using.

We can use VS Code's workspaces to act as a profile switcher.

Create an empty workspace
Enable extensions for the workspace
Configure workspace specific settings
Add project to workspace

This workspace is now configured with all the extensions and settings that I need for working on a Rust project.

Angular: Determine previous page URL

C.OG — Fri, 19 Feb 2021 22:32:58 +0000

The getCurrentNavigation method of the angular router returns a property previousNavigation that has details on the previous navigation.

This can be used to determine the previous page url, or even if there was no previous navigation (initial load of a particular route).

It's worth noting that this method only works when used in the constructor of a components class.

export class SomeComponent  {

  constructor(
    private router: Router,
  ) {
  const previousNavigation = this.router.getCurrentNavigation().previousNavigation;

  const previousUrl = previousNavigation.finalUrl;
  }
}

More on the Router.getCurrentNavigation() method

RxJS Patterns: Creating an Action Stream

C.OG — Wed, 09 Oct 2019 18:15:50 +0000

RxJS is an extremely powerful observable based library, used at the very core of Angular, that allows us to write our applications in a truly reactive paradigm.

Creation operators are standalone functions that can create a new observable.

of(1,2,3)
  .subscribe((val) => {
    console.log('::val', val) // output: 1, 2, 3
  })

These type of operators pose a new challenge when you want to follow a truly reactive paradigm.

In #rxjs .subscribe() is where reactive programming ends
— Michael Rx Hladky (@michael_hladky) October 5, 2019

Using observables comes with a greater responsibility of always unsubscribing. Fortunately Angular provides an async pipe that handles the subscription and un-subscription logic for us. This worked great until I had to make a http post request.

There was no obvious way to use the async pipe in this context, as this request is made upon a user action. And I really, really, did not want to use .subscribe().

Cue the action stream:

<!-- some.component.html -->

<ng-container *ngIf="{ postAction: postStream$ | async } as postStream">

We subscribe to a postStream$ using the async pipe. The observable will not emit any values until the http request has returned, therefore, we wrap the subscription in an object. This will be a truthy value, so the *ngIf condition will be met, which allows our template to always be rendered.

The complete template:

<!-- some.component.html -->

<ng-container *ngIf="{ postAction: postStream$ | async } as postStream">
  <p>Click the button to see the magic happen :)</p>
  <button (click)="onBtnClick()">Post data to back end</button>

  <!-- You can use this to show a success or error message, or loading state -->
  <p *ngIf="postStream.postAction">Saved!</p>
</ng-container>

In our component file:

// app.component.ts

// create your action stream
private readonly postAction$ = new Subject();

We create an action stream; simply a subject that we'll call .next() on when an event in our template has taken place.

// app.component.ts

// subscribe to this post stream (high order observable) in your template to start listening 
// for values emitted by the action stream
postStream$ = this.postAction$.pipe(
  // pick the correct operator for your use case
  exhaustMap(()=> {
    return of('my post'); // this could be your http post
  })
)

We create a higher order observable postStream$, that has an outer observable, our action stream we created earlier, and an inner observable that we map to. For this example we use a creation operator of() but this could be a http post request.

// app.component.ts

onBtnClick() {
  this.postAction$.next()
}

We then have a method on the class that will trigger our action stream.

The complete component:

// app.component.ts

export class AppComponent  {
  // create your action stream
  private readonly postAction$ = new Subject();

  // subscribe to this post stream (high order observable) in your template to start listening 
  // for values emitted by the action stream
  postStream$ = this.postAction$.pipe(
    // pick the correct operator for your use case
    exhaustMap(()=> {
      return of('my post'); // this could be your http post
    })
  )

  onBtnClick() {
    this.postAction$.next()
  }
}

With this approach, we can avoid having to manually call .subscribe() when making http post requests.

You can find the full code on StackBlitz

Sizing Units in CSS: REM and EM

C.OG — Tue, 24 Sep 2019 08:42:12 +0000

CSS has different units for expressing length. Many units take a length property, such as: font-size, padding, width etc. There are two types of length units: absolute and relative.

This article focuses on two relative units: REM and EM. We discuss how the browser converts these into absolute units.

REM to PX

The browser uses the root element's (html) font size as the multiplier when converting to pixels.

html {
  font-size: 16px;
}

h1 {
  font-size: 1rem; 
}

In this example, the font-size of the h1 will be 16px.

The calculation the browser runs:

# root font size * property rem unit = px value
            16px * 1rem              = 16px

EM to PX

The browser uses the font-size of the element that is being styled as the multiplier when converting to pixels. It will bubble up until it gets the first explicit font-size definition.

html {
  font-size: 16px;
}

div {
  font-size: 22px;
}

div h1 {
  font-size: 2em
}

In this example, the font-size of the h1 will be 44px.

The calculation the browser runs:

# element font size * property em unit = px value
               22px * 2em              = 44px

In this scenario, the element font size is inherited from the parent div

It's important to remember that font-size inheritance will come into effect if no font-size is explicitly set. For rem, if there is no font-size explicitly set on the root element, it will inherit the value from the browser settings.

Git: Exclude a folder when diffing

C.OG — Fri, 13 Sep 2019 12:22:42 +0000

When doing a git diff, especially between branches, you may be greeted with a mountain of changes that you have to sift through to find what you're looking for.

Consider excluding certain folders:

git diff -- ':!<folder-name>'

You can also exclude multiple folders:

git diff -- ':!<folder-name>' ':!<other-folder>'`

TypeScript: How to set a new property on the window object

C.OG — Fri, 13 Sep 2019 11:40:02 +0000

When merging global interfaces in TypeScript, you have to declare the interface in the global scope.

export declare global {
  interface Window {
    // add you custom properties and methods
    YT:(videoID: string, options?: {}) => Observable<YtResponse>
  }
}

TypeScript supports declaration merging, the premise is the same for global objects. The difference is to declare the interface as part of the global scope.

The Fullstack Angular Developer

C.OG — Wed, 17 Jul 2019 07:58:32 +0000

TLDR: The parallels between an Angular and NestJS app are striking. You can share types, functions et al between the two platforms, allowing you, an Angular developer, to write a fully featured Backend application using Angular paradigms.

My thoughts on the term “Fullstack” are firmly attached to a pendulum. It’s currently swinging in the region of “there is no such thing”. Each discipline alone is too broad to have in-depth knowledge on both. You may be able to spin up an API server with Express, but that doesn’t make you “Fullstack”.

Nevertheless, the term Fullstack is present in our industry and I've seen a number of job postings that have a React + NodeJS pairing. This got me thinking about what the stack would be in the Angular ecosystem. Behold, NestJS.

We recently had to build a feature that required some Restful APIs. In order not to be blocked, we went down the "easier" 🤨 route of creating our own with NodeJS. We were already using Nx to manage our monorepo so it was trivial to add NestJS to our project.

The learning curve was next to nothing. NestJS was heavily inspired by Angular, so you'll feel right at home. TypeScript, Decorators, Services, Modules etc are all featured in Nest. It also does a really good job at abstracting some key concepts when it comes to creating Restful API's. HTTP response codes are automatically returned. Get, Post methods and a majority of other enhanced functionality are handled by decorators.

The biggest barrier I find when learning a new framework or library is the documentation and lack of available resources. Thankfully this is not an issue with NestJS. The docs are beautiful and due to the rise in popularity of Nest, there are a ton of helpful resources. In addition to that, there are schematics for the Angular CLI, so scaffolding is a breeze.

Eventually, I see the Angular + Nest stack becoming the de facto for full stack Angular Applications. The low barrier to entry for Angular developers makes it a dream pairing.

Here we go!

C.OG — Sat, 27 Apr 2019 10:25:08 +0000

I have conquered it!

"Conquered what?", you'll be asking. I've attempted to start micro blogging over 2 years. For some reason, I still haven't been able to press publish on any of the countless drafts!

I struggled to decide on what the first post should be about. Does it have to be an explainer of the blog, or just go straight into it; what if it doesn't read well, what if it doesn't sound cohesive? All valid questions.

As you read this, whether it reads well or not, whether it's cohesive or not. It doesn't matter, because, I have finally been able to press PUBLISH! (Or submit in this case)

DEV Community: C.OG

Solana teardown: Walkthrough of the example helloworld program

Who this article is for

Use declaration

Greeting Account

Entrypoint

process_instruction

program_id

accounts

instruction_data

Logging

Accounts

Validation and Security

Serialization / Deserialization

Resources

Footnotes

Solana: How to send custom instructions via instruction data

Define API of the program

Decode instruction_data

Update process_instruction

Update sayHello

Create createSayHelloInstructionData

Update process_instruction

VS Code Knowledge Pill: Profiles switching using Workspaces

Angular: Determine previous page URL

RxJS Patterns: Creating an Action Stream

Sizing Units in CSS: REM and EM

REM to PX

EM to PX

Git: Exclude a folder when diffing

TypeScript: How to set a new property on the window object

The Fullstack Angular Developer

Here we go!

I have conquered it!

Decode `instruction_data`

Update `process_instruction`

Update `sayHello`

Create `createSayHelloInstructionData`

Update `process_instruction`