External module

The @external annotation allows a blockchain to access entities defined in another blockchain in the same container.

@external("foo")
namespace {
    @log
    entity user {
    }
    @log
    entity company {
    }
}

@external("foo")
@log
entity city {
}

query get_all_users() = user @* { };

In this example, 'foo' is the name of an external blockchain. Before it's used in an @external annotation, you need to define the blockchain in the blockchain configuration (dependencies node).

Every blockchain has its chain_id, that's included in table names for entities and objects of that chain. If the blockchain 'foo' has chain_id = 123, the table for the entity user is c123.user.

Key features

• External entities must have the @log annotation. This implies that those entities can't have mutable attributes.
• You can't create or delete the values of external entities.
• You can annotate only entities, namespaces, and imports with @externalannotation.
• When you select the values of an external entity (using at-expression), an implicit block height filter gets applied, so the active blockchain can see only those blocks of the external blockchain whose height is lower than a specific value.
• Every blockchain stores the structure of its entities in meta-information tables. When you start a blockchain, the meta-information of all involved external blockchains gets verified to ensure that all declared external entities exist and have declared attributes.

note

External modules can only be accessed if the blockchain resides in the same container as the one trying to access them.

External modules

You can annotate a module as @external with no arguments.

Example

@external
module;

@log
entity user {
}

@log
entity company {
}

External modules can contain only namespaces, entities (annotated with @log), and imports of other external modules.

External modules can be imported as a regular or external module:

• Regular import: entities defined in the module ext belong to the current blockchain.

  import ext;

• External import: entities defined in the module ext get imported as external entities from the chain foo.

  @external('foo') import ext;

Transactions and blocks

To access blocks and transactions of an external blockchain, you use the following syntax:

@external("foo")
namespace foo {
    entity transaction ;
    entity block ;
}

function get_foo_transactions(): list<foo.transaction> = foo.transaction @* { };

function get_foo_blocks(): list<foo.block> = foo.block @* { };

• External and non-external transactions/blocks are distinct, incompatible types.
• When selecting external transactions or blocks, you use an implicit height filter (like for external entities).

You can access entities transaction and block of an external chain by an external module:

@external("foo")
import ext;

function get_foo_transactions(): list<ext.transaction> = ext.transaction @* { };

function get_foo_blocks(): list<ext.block> = ext.block @* { };

The entities are implicitly added to the module's namespace, and you can access them by their import alias.