> For the complete documentation index, see [llms.txt](https://mapo.gitbook.io/dev-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mapo.gitbook.io/dev-docs/fundamentals/smart-contracts/basics.md).

# Basics

This guide covers the fundamentals of smart contracts on MAPO-Relay-Chain, including the Solidity language, contract structure, libraries, and composability.

### Solidity Language

MAPO smart contracts primarily use Solidity as the programming language.

* Object-oriented, high-level language for implementing smart contracts
* Curly-bracket syntax influenced by C++
* Statically typed (variable types known at compile time)
* Supports inheritance, libraries, and complex user-defined types

#### Example Contract

```solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >= 0.7.0;

contract Coin {
    address public minter;
    mapping (address => uint) public balances;

    event Sent(address from, address to, uint amount);

    constructor() {
        minter = msg.sender;
    }

    function mint(address receiver, uint amount) public {
        require(msg.sender == minter);
        balances[receiver] += amount;
    }

    function send(address receiver, uint amount) public {
        require(amount <= balances[msg.sender], "Insufficient balance.");
        balances[msg.sender] -= amount;
        balances[receiver] += amount;
        emit Sent(msg.sender, receiver, amount);
    }
}
```

#### Solidity Resources

* [Documentation](https://docs.soliditylang.org/en/latest/)
* [Solidity by Example](https://docs.soliditylang.org/en/latest/solidity-by-example.html)
* [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts)

### Contract Anatomy

A smart contract is a program that runs at an address on MAPO. It's made up of data and functions that execute upon receiving a transaction.

#### Data Storage

**Storage** - Persistent data stored permanently on the blockchain:

```solidity
contract SimpleStorage {
    uint storedData; // State variable
}
```

**Memory** - Temporary data for function execution lifetime, much cheaper to use.

**Environment Variables** - Special global variables:

| Variable          | Type    | Description                          |
| ----------------- | ------- | ------------------------------------ |
| `block.timestamp` | uint256 | Current block epoch timestamp        |
| `msg.sender`      | address | Sender of the message (current call) |

#### Functions

Functions can get or set information in response to transactions:

* **internal** - Don't create an EVM call, only accessible within contract
* **external** - Create an EVM call, part of contract interface
* **public** - Can be called internally or externally
* **private** - Only visible within defining contract

```solidity
// View function - doesn't modify state
function balanceOf(address _owner) public view returns (uint256) {
    return ownerBalance[_owner];
}

// State-changing function
function update_name(string value) public {
    dapp_name = value;
}
```

#### Constructor

Executed once when the contract is first deployed:

```solidity
constructor() public {
    owner = msg.sender;
}
```

#### Events and Logs

Events communicate with frontend applications:

```solidity
event Transfer(address from, address to, uint amount);
emit Transfer(msg.sender, receiver, amount);
```

### Libraries

Smart contract libraries provide reusable building blocks so you don't have to reinvent the wheel.

#### Common Patterns

**Ownable** - Restricts access to contract owner:

```solidity
contract Ownable {
    address public owner;
    
    constructor() internal {
        owner = msg.sender;
    }
    
    modifier onlyOwner() {
        require(owner == msg.sender, "Ownable: caller is not the owner");
        _;
    }
}
```

**SafeMath** - Arithmetic with overflow checks (built into Solidity 0.8+)

#### Using Libraries

```solidity
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";

contract MyNFT is ERC721 {
    constructor() ERC721("MyNFT", "MNFT") public { }
}
```

#### Popular Libraries

| Library                                                  | Description                                                |
| -------------------------------------------------------- | ---------------------------------------------------------- |
| [OpenZeppelin](https://docs.openzeppelin.com/contracts/) | Most popular library for secure smart contract development |
| [DappSys](https://dappsys.readthedocs.io/)               | Safe, simple, flexible building-blocks                     |

### Composability

Smart contracts are public and can be thought of as open APIs. You can use existing contracts as building blocks for your project.

#### Principles

1. **Modularity** - Each contract performs a specific task
2. **Autonomy** - Contracts operate independently and are self-executing
3. **Discoverability** - Contracts are open-source and publicly available

#### Benefits

* **Shorter development cycle** - Reuse existing solutions
* **Greater innovation** - Focus on new features instead of basic functionality
* **Better user experience** - Interoperability between dapps

#### Example: Flash Loans

Flash loans demonstrate composability - borrowing assets without collateral, using them across multiple protocols, and repaying within one transaction. This requires combining calls to multiple contracts.

### Further Reading

* [Solidity Documentation](https://solidity.readthedocs.io/)
* [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts)
* [Composability is Innovation](https://future.a16z.com/how-composability-unlocks-crypto-and-everything-else/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mapo.gitbook.io/dev-docs/fundamentals/smart-contracts/basics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.