Contract Anatomy

Let’s explore the basic anatomy of a simple “Hello World” contract to understand how NEAR smart contracts are structured.

Importing the SDK

All contracts import the NEAR SDK, enabling them to access the execution environment, call other contracts, transfer tokens, and much more.

Rust
JavaScript

use near_sdk::near;

import { NearBindgen, near, call, view } from 'near-sdk-js';

You can also use third-party libraries, though some might not work due to the limitations of the contract runtime.

Contract Structure

The contract is described through a structure:

The attributes define which data the contract stores
The functions define its public (and private) interface

Rust
JavaScript

use near_sdk::near;

#[near(contract_state)]
pub struct Contract {
    greeting: String,
}

#[near]
impl Contract {
    #[init]
    pub fn new() -> Self {
        Self {
            greeting: "Hello".to_string(),
        }
    }

    pub fn get_greeting(&self) -> String {
        self.greeting.clone()
    }

    pub fn set_greeting(&mut self, greeting: String) {
        self.greeting = greeting;
    }
}

Contract Struct MacroThe #[near(contract_state)] macro tells the SDK that this structure defines the contract’s state, so it knows:

What to fetch from storage when the contract is loaded
What to store when the contract is done executing

The #[near] macro tells the SDK which functions are exposed to the outside world.Note: Only one struct can be decorated with the #[near(contract_state)] macro.

import { NearBindgen, near, call, view } from 'near-sdk-js';

@NearBindgen({})
class HelloContract {
  greeting: string = "Hello";

  schema = {
    greeting: "string"
  };

  @view({})
  get_greeting(): string {
    return this.greeting;
  }

  @call({})
  set_greeting({ greeting }: { greeting: string }): void {
    near.log(`Saving greeting: ${greeting}`);
    this.greeting = greeting;
  }
}

Contract Class DecoratorThe @NearBindgen decorator tells the SDK which class defines the contract, so it knows:

What to fetch from storage when the contract is loaded
What to store when the contract is done executing
The methods that are exposed to the outside world
If the contract needs to be initialized

Note: Only one class can be decorated with the @NearBindgen decorator.

JavaScript contracts need to include a schema object that defines the contract’s state and its types. This object is used by the SDK to correctly serialize and deserialize the contract’s state.

Storage (State)

We call the data stored in the contract the contract’s state. In our Hello World example, the contract stores a single string (greeting), and the state starts initialized with the default value "Hello".

Rust
JavaScript

#[near(contract_state)]
pub struct Contract {
    greeting: String,  // This field is stored in the contract's state
}

impl Default for Contract {
    fn default() -> Self {
        Self {
            greeting: "Hello".to_string(),
        }
    }
}

@NearBindgen({})
class HelloContract {
  greeting: string = "Hello";  // Default value

  schema = {
    greeting: "string"  // Type definition
  };
}

Learn More About State

Deep dive into contract state management and storage

Read-Only Functions

Contract functions can be read-only, meaning they don’t modify the state. Calling them is free for everyone, and does not require having a NEAR account.

Rust
JavaScript

// Read-only functions take an immutable reference to self
pub fn get_greeting(&self) -> String {
    self.greeting.clone()
}

In Rust, read-only functions are those that take an immutable reference to self (&self).

// Read-only functions are marked with @view
@view({})
get_greeting(): string {
  return this.greeting;
}

In JavaScript, read-only functions are marked with the @view({}) decorator.

Learn More About Functions

Explore all function types and their use cases

State-Changing Functions

Functions that modify the state or call other contracts are considered state-changing functions. It is necessary to have a NEAR account to call them, as they require a transaction to be sent to the network.

Rust
JavaScript

// State-changing functions take a mutable reference to self
pub fn set_greeting(&mut self, greeting: String) {
    near_sdk::log!("Saving greeting: {}", greeting);
    self.greeting = greeting;
}

In Rust, state-changing functions are those that take a mutable reference to self (&mut self).

// State-changing functions are marked with @call
@call({})
set_greeting({ greeting }: { greeting: string }): void {
  near.log(`Saving greeting: ${greeting}`);
  this.greeting = greeting;
}

In JavaScript, state-changing functions are marked with the @call({}) decorator.

Contextual Information

The SDK provides contextual information about the execution environment, such as:

Who called the function - predecessor_account_id
Current block timestamp - block_timestamp
Attached deposit - attached_deposit
Available gas - prepaid_gas

Rust
JavaScript

use near_sdk::{env, AccountId, Balance};

pub fn get_caller(&self) -> AccountId {
    env::predecessor_account_id()
}

pub fn get_timestamp(&self) -> u64 {
    env::block_timestamp()
}

#[payable]
pub fn get_deposit(&self) -> Balance {
    env::attached_deposit().as_yoctonear()
}

import { near } from 'near-sdk-js';

@view({})
get_caller(): string {
  return near.predecessorAccountId();
}

@view({})
get_timestamp(): string {
  return near.blockTimestamp();
}

@call({ payableFunction: true })
get_deposit(): string {
  return near.attachedDeposit().toString();
}

Internal Functions

Contracts can also have private internal functions - such as helper or utility functions - that are not exposed to the outside world.

Rust
JavaScript

#[near]
impl Contract {
    // Public function - exposed to external callers
    pub fn increment(&mut self) {
        self.internal_increment();
    }

    // Private function - not exposed externally
    fn internal_increment(&mut self) {
        self.counter += 1;
    }
}

To create internal private methods in Rust, do not declare them as public (pub fn).

@NearBindgen({})
class Contract {
  counter: number = 0;

  // Public function - exposed to external callers
  @call({})
  increment(): void {
    this.internal_increment();
  }

  // Private function - not exposed externally
  internal_increment(): void {
    this.counter += 1;
  }
}

To create internal private methods in JavaScript, simply omit the @view and @call decorators.

Next Steps

Functions

Learn about all function types

Storage

Understand state management

Cross-Contract Calls

Call other contracts

Testing

Test your contracts

Getting Started

Protocol

Smart Contracts

Web3 Applications

AI and Agents

Chain Abstraction

Primitives

Data Infrastructure

Importing the SDK

Contract Structure

Storage (State)

Learn More About State

Read-Only Functions

Learn More About Functions

State-Changing Functions

Contextual Information

Internal Functions

Next Steps

Functions

Storage

Cross-Contract Calls

Testing

Build docs developers (and LLMs) love

Getting Started

Protocol

Smart Contracts

Web3 Applications

AI and Agents

Chain Abstraction

Primitives

Data Infrastructure

​Importing the SDK

​Contract Structure

​Storage (State)

Learn More About State

​Read-Only Functions

Learn More About Functions

​State-Changing Functions

​Contextual Information

​Internal Functions

​Next Steps

Functions

Storage

Cross-Contract Calls

Testing

Build docs developers (and LLMs) love

Importing the SDK

Contract Structure

Storage (State)

Read-Only Functions

State-Changing Functions

Contextual Information

Internal Functions

Next Steps