Andromeda
Ask or search…
K

Virtual File System

Introduction

The Virtual File System (VFS) is a part of the Andromeda Messaging System (AMP) which was heavily inspired by the linux file system. Users can register their address to a username. They can also register ADOs to paths. These paths can then be used and referenced in our ADO systems.
Addresses may only be registered by the child or parent. This means a child can register its name relative to its parent (AddParentPath) or a parent may register its child (AddPath).
When an Andromeda App is made, it will register all paths for its child components and also register itself as a child of the instantiating address. Each component under the App is registered by its name, and the App itself is registered under its assigned name.
In addition to paths, symbolic links that point to a path can be created by users.

Example:

A user does the following:
  1. 1.
    Registers their address as user1 by calling RegisterUser
  2. 2.
    The user then creates an App and calls it "app-1" which has 2 compnents named "comp-1" and "comp-2"
  3. 3.
    The App registers its components under their assigned names
When you register a username, it will registered in the "home" directory. This can also be represented by the "~" symbol.
In the examples below, /home can be replace by ~ in the paths. For example, /home/user1 and ~/user1 are considered the same.
The following paths are now registered:
  • /home/user1 will resolve the the user's address
  • /home/user1/app-1 is the path to get the address of the app contract
  • /home/user/app-1/comp-1 is the path to get the address of component 1 in the app
  • /home/user/app-1/comp-2 is the path to get the address of component 2 in the app
When you go through our ADOs, you will notice an AndrAddr struct used very frequently for specifying addresses, whether be user addresses or ADO addresses. The use of this struct signifies that the address can be referenced by either the VFS path or the user/contract address. More on the AndrAddr struct can be found here.
In case you want to reference a component in the app itself, you can use ./component as a valid path. For example if I want to create an app with two components named "token" and "auction" and in the auction I want to reference the token address, I can use ./token to do so.

IBC Paths

When sending IBC messages, the recipient of the message needs to be a valid IBC VFS path. The path is formatted in the following manner:
<protocol>://<chain>/<path>
Ado_type: vfs

InstantiateMsg

Rust
JSON
pub struct InstantiateMsg {
pub kernel_address: String,
pub owner: Option<String>,
}
{
"kernel_address":"andr1..."
}
Name
Type
Description
kernel_address
String
Address of the Kernel contract on chain. Can be found in our deployed contracts.
owner
String
Optional address to specify as the owner of the ADO being created. Defaultes to the sender if not specified.

ExecuteMsg

AddPath

Registers a component to the path.
Only accepts alphanumeric charaters.
If user1 registers ado1, then the path created would be /home/user1/ado1.
Registering a path that is already found will overwrite the old path.
Note that you will rarely need to call the AddPath execute message yourself. When Andromeda Apps are instantiated, it is automatically called, registering the App as a child to the sender's username and each of the components as children of the App itself similar to what we saw in the example above.
Rust
JSON
pub enum ExecuteMsg {
AddPath {
name: String,
address: Addr,
parent_address:Option<AndrAddr>
}
}
{
"add_path":{
"name":"ado1",
"address":"andr1..."
}
}
Name
Type
Description
name
String
The name of the component in the path.
address
Addr
The address of the component.
parent_address
Option<AndrAddr>
Optional address to specify as the parent for the component. If not specified, then the sender will be the parent by default.
Creates a symbolic link that points to a specific path.
Rust
JSON
pub enum ExecuteMsg {
AddSymlink {
name: String,
symlink: AndrAddr,
parent_address: Option<AndrAddr>,
}
}
{
"add_symlink":{
"name":"my-link",
"symlink":"/home/user2/app1"
}
}
Name
Type
Description
name
String
The name of the symlink.
symlink
AndrAddr
The path to point to.
parent_address
Option<AndrAddr>
The address to register the symlink under.
In the JSON example above, if the username of the sender (parent address) is user1, then the symlink /home/user1/my-link would resolve to the path /home/user2/app1.

RegisterUser

Registers a username to an address.
You can only register a username for your address (sender).
Only accepts alphanumeric charaters.
Usernames are unique, meaning no two users can have the same username.
If address is provided sender must be Kernel.
Rust
JSON
pub enum ExecuteMsg{
RegisterUser {
username: String,
address: Option<Addr>,
}
}
{
"register_user":{
"username":"user1"
}
}
Name
Type
Description
username
String
The username to register.
address
Option<Addr>
The address to register the username to (Only available to the kernel).

RegisterUserCrossChain

Registers the username of the sender on another chain.
Registerning a username on another chain needs to be done through the Andromeda chain first. Once the username is registered on the second chain, it is possible to register it to a third chain through Andromeda or the second chain.
For example, if I want to register my username on Juno and then Terra, I would need to call RegisterUserCrossChain message from the Andromeda chain FIRST specifying the chain field as juno. Once registered on Juno, I can call the message from either Andromeda or Juno to register it on Terra.
Rust
JSON
pub enum ExecuteMsg {
RegisterUserCrossChain {
chain: String,
address: String,
},
}
// Some code
Name
Type
Description
chain
String
The name of the chain you want to register the username on.
address
String
The address on the specified chain to register the username to.

RegisterLibrary

Registers a library address under a library name. Libraries will be set up by Andromeda, and will contain a group of paths that resolve to addresses that can be used by users to create Apps. Users can use the SubDir query to get all the directories that are saved under the library name.
This message cannot be called by a user.
Rust
pub enum Execute {
RegisterLibrary {
lib_name: String,
lib_address: Addr,
}
}
Name
Type
Description
lib_name
String
The name of the library.
lib_address
Addr
The address of the library.

AddParentPath

Registers the child's path relative to the parent.
For example, if I call AddParentPath specifying the name as test and the parent_address as ~/parent, then the path ~/parent/test would resolve to my address.
Only accepts alphanumeric characters.
Rust
JSON
pub enum ExecuteMsg {
AddParentPath {
name: String,
parent_address: AndrAddr,
}
}
{
"add_parent_path":{
"name": "ado7",
"parent_address":"/user1/app1"
}
}
Name
Type
Description
name
String
The name to assign.
parent_address
AndrAddr
The address of the parent ADO.

Base Executes

The rest of the execute messages can be found in the ADO Base section.

QueryMsg

ResolvePath

Gets the address of the specified path.
Rust
JSON
pub enum QueryMsg {
#[returns(Addr)]
ResolvePath { path: AndrAddr },
}
{
"resolve_path":{
"path":"~/user1/app1/ado2"
}
}
Name
Type
Description
path
AndrAddr
The path to get the address for.
Returns the address of of the path. In the above JSON example, the address of ado2 would be returned.

SubDir

Gets all the paths under the specified directory.
Rust
JSON
pub enum QueryMsg {
#[returns(Vec<PathDetails>)]
SubDir { path: AndrAddr },
}
{
"sub_dir":{
"path":"~/user1/app1"
}
}
Name
Type
Description
path
AndrAddr
The path to get all sub directories for.
In the JSON example provided above, all paths under ~/user1/app1 will be returned. This would be all the component paths of the App app1.

Paths

Gets all the paths that resolve to the specified address.
Rust
JSON
pub enum QueryMsg {
#[returns(Vec<String>)]
Paths { addr: Addr },
}
{
"paths":{
"addr":"andr1..."
}
}
Name
Type
Description
addr
Addr
The address to get the paths for.

GetUsername

Gets the registered username of the specified address.
Rust
JSON
pub enum QueryMsg {
#[returns(String)]
GetUsername { address: Addr },
}
{
"get_username":{
"address":"andr1..."
}
}
Name
Type
Description
address
Addr
The address to get the username for.

GetLibrary

Gets the library name of the specified library address.
Rust
JSON
pub enum QueryMsg {
#[returns(String)]
GetLibrary { address: Addr },
}
{
"get_library":{
"address":"andr1..."
}
}
Name
Type
Description
address
Addr
The address of the library to get the name for.
Returns the path that the specified symlink points to.
Rust
JSON
pub enum QueryMsg {
#[returns(AndrAddr)]
ResolveSymlink { path:AndrAddr },
}
{
"resolve_symlink":{
"path":"~/user1/symlink1"
}
}
Name
Type
Description
path
AndrAddr
The path of the symlink to resolve.

Base Queries

The rest of the query messages can be found in the ADO Base section.