Skip to content

Commit

Permalink
docs: fix doc images (#10)
Browse files Browse the repository at this point in the history
  • Loading branch information
roberts-pumpurs authored Jan 30, 2025
1 parent ea01735 commit bf33510
Show file tree
Hide file tree
Showing 4 changed files with 12 additions and 11 deletions.
8 changes: 4 additions & 4 deletions solana/crates/axelar-executable/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ If we look at the event data that the EVM Gateway produces when making a [`gatew

Relayer for the edge chain **must** know how to call a contract on the given edge chain so that the contract can properly process the Axelar GMP message. The same concept applies to Solana, that every contract that wants to be compatible with the Axelar protocol **must** implement the `axelar-executable` interface. Implementing the `axelar-executable` interface allows the Relayer to send transactions to it.


![high level interactoin](https://github.com/user-attachments/assets/d073fe0d-9497-4b19-b5f6-af895ea8587f)
![high level interactoin](https://github.com/user-attachments/assets/c676c8c6-8867-4560-a0cc-fa476b2b21a7)

1. Relayer will compose a transaction that can interact with the destination program on Solana
2. `axelar-executable` exposes a function that allows the program to parse the Message into a format that it can work with
Expand Down Expand Up @@ -52,7 +51,8 @@ This means that the base interface for GMP messages defined by the Axelar protoc

Solanas `axelar-executable` now expects that the `payload` emitted on the source chain also includes all the `account[]` data for the Relayer to create a proper transaction. If the `account[]` is absent on the GMP call, the Relayer cannot know what accounts to provide when calling the destination contract.

![image](https://github.com/user-attachments/assets/82a2ff39-fec4-4a3a-a894-fe1171a65585)
![Axelar Message Payload](https://github.com/user-attachments/assets/29a96677-83f5-4727-befa-3f815e31ad39)


The source chain that wants to interact with Solana must encode the messages in a specific format that the Solana destination contract understands, and the Relayer can understand. `Accounts[]` requirement also lets the Relayer deterministically derive the accounts when crafting the transaction.

Expand Down Expand Up @@ -88,7 +88,7 @@ The way how accounts and the payload are encoded is encoding-specific. The `axel

You can see the anatomy of an instruction that the Solana Relayer will send to the destination program when sending the raw payload to it:

![image](https://github.com/user-attachments/assets/fecac1d3-cb81-4626-ade5-ca2f8d79697d)
![Anatomy of an ix](https://github.com/user-attachments/assets/0312abb4-fe7f-45c7-a8ae-1318489da9d2)


## Exceptions of the `accounts[]` rule: ITS & Governance
Expand Down
11 changes: 6 additions & 5 deletions solana/crates/axelar-solana-encoding/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ While `abi` encoding can be used inside Solana programs, the ecosystem primarily
The `axelar-solana-encoding` crate uses Merkle Trees to Merkelise the data and builds commitment schemes. This is necessary because Solana TX and compute limitations prevent doing _everything_ that the EVM gateway can do in a single TX. The defining property of `axelar-solana-encoding` allows the Relayer to send many small transactions without complex on-chain state tracking. Merkle Roots are the commitment values that tie all the small transactions together.

![image](https://github.com/user-attachments/assets/84047adf-15de-4473-aad1-7851e65718eb)
![Merkle Tree visualisation](https://github.com/user-attachments/assets/6cce2c07-2299-497d-bfdb-e889d3ac67dc)

The fundamental idea of the Merkle Tree:
- You can prove that an item is part of the set without requiring the whole set present (e.g. prove **that a message is part of the message batch** or a **verifier is part of a verifier set**)
Expand All @@ -33,7 +33,7 @@ The unique property of this approach is that:

Let's take a look at how we construct leaf nodes from verifier sets and message batches:

![image](https://github.com/user-attachments/assets/825de271-9655-4611-8a0b-7a27ff2e6d73)
![Merkelising the Data](https://github.com/user-attachments/assets/6bbb91c6-7ba1-4c35-a770-cead1a97dc1a)

> [!NOTE]
> **Payload digest**: this is the data that the verifiers sign. It is a hash that consists of all the messages, verifiers, and other metadata.
Expand All @@ -51,7 +51,7 @@ Let's take a look at how we construct leaf nodes from verifier sets and message
> [!NOTE]
> **Execute Data**: This is the data that the Multisig Prover returns after getting all the signatures. It aggregates the signatures and all the data used to create a **payload digest**. The goal of the data is to allow the gateway to check that the verifiers have signed a payload digest and that the provided messages can be re-hashed to create the payload digest.
![image](https://github.com/user-attachments/assets/066bf866-4130-4808-8901-5bf493d895fb)
![Execute Data layout](https://github.com/user-attachments/assets/7a6b784b-32a5-42cb-adee-26cdd430fe84)

After the data has been Merkelised, the Multisig Prover neatly packs it together for the Relayer to consume.
It encodes:
Expand Down Expand Up @@ -81,7 +81,7 @@ This means that our `axelar-solana-encoding` code has a branching mechanism that
- on Axelars CosmWASM runtime (Multisig Prover), we leverage the Rust-native keccak256 implementation
- on the Relayer, we leverage the Rust-native keccak256 implementation

![image](https://github.com/user-attachments/assets/d8257c24-abb2-4064-9414-b50618bb07e4)
![Hashing the data](https://github.com/user-attachments/assets/fe3f4006-6131-40af-a775-df6291bb3f8f)

For encoding the data, we use [udigest crate](https://docs.rs/udigest/0.2.2/udigest/encoding/index.html), which allows us to transform a set of data into a vector of bytes. [Read this article about hashing the data and creating digests](https://www.dfns.co/article/unambiguous-hashing).

Expand All @@ -108,7 +108,8 @@ The _Storage Limit for Messages_ requirement is a given using Solana PDAs, no ex
## Understanding the EVM encoding for comparison sake

To better understand how this approach differs from the EVM Gateways ABI encoding, let's analyze it. The EVM encoding works the following way:
[![evm encoding](https://github.com/user-attachments/assets/9ffb61a4-74ec-4734-862a-1027fa0e797b)](https://link.excalidraw.com/readonly/91ctxas9n1417Y1XXKwQ)

![evm abi encoding](https://github.com/user-attachments/assets/3e3c32a8-13fe-482a-9d9c-a9f4853a63cc)

Summary from the **payload digest**:
- all messages in a batch get encoded and hashed in one go
Expand Down
2 changes: 1 addition & 1 deletion solana/programs/axelar-solana-governance/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

## High level overview

[![governance hl](https://github.com/user-attachments/assets/d771438c-b7ac-4d69-92d7-3c131ce91bd9)](https://excalidraw.com/#json=pVoAXLtjUps5y9nU8wYu2,cz_P-xoEobAN9qbfe0-MwQ)
[![governance hl](https://github.com/user-attachments/assets/1d5be514-67d9-4dd6-b635-375300f01ae5)](https://excalidraw.com/#json=pVoAXLtjUps5y9nU8wYu2,cz_P-xoEobAN9qbfe0-MwQ)

The governance module allows decisions taken on the Axelar network to be propagated and executed on the different integrated chains, giving a chance (by timelock) to each chain maintainer to prepare for it's execution. So the governance module acts as a "approved proposal's forwarder" which is connected to the Axelar governance infrastructure via [GMP](https://www.axelar.network/blog/general-message-passing-and-how-can-it-change-web3) messages.

Expand Down
2 changes: 1 addition & 1 deletion solana/programs/axelar-solana-its/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ The ITS implements functionality to allow token transfers to carry instruction d

The diagram below shows how the message flows from the EVM ITS contract to a Solana program while also showing how the message is structured (click to open on Excalidraw an be able to zoom-in).

[![EVM->Solana](https://github.com/user-attachments/assets/4f046eb8-39ec-4c04-885e-865f90f7513b)](https://excalidraw.com/#json=0lVeKwoyvgoGjZqq37iVP,dHVboAUXzZ-tsfo2KUizpQ)
[![EVM->Solana](https://github.com/user-attachments/assets/bf0bf75e-3acc-404e-8425-0d7779a2893b)](https://excalidraw.com/#json=0lVeKwoyvgoGjZqq37iVP,dHVboAUXzZ-tsfo2KUizpQ)

When calling a contract on the Solana chain using this flow, the Solana instruction should be serialized using Borsh (as expected by the solana program). Due to the Solana account model, the accounts required by the instruction should also be provided. The [AbiSolanaGateway](../../../evm-contracts/src/SolanaGatewayPayload.sol#L20) solidity library can be used directly or as a guide for creating the executable payload to send from EVM to Solana. This payload should then be used to populate the `data` field of the `InterchainTransfer` message.

Expand Down

0 comments on commit bf33510

Please sign in to comment.