Skip to main content

GLOs

A Generic Ledger Operation (GLO) is a declarative structure that defines operations that can be performed on any distributed ledger technology (DLT).

GLOs insulate developers from the nitty gritty details of interacting with blockchain, allowing developers to focus on the application business logic and less on going through steep learning curves and specifics for each DLTs in use.

MARCO platform translates GLOs into Ledger Specific Operations (LSO) and runs them on the underlying DLT network.

graph LR MARCO(GLO Resolver) GLO(GLO) ETHLSO(Eth LSO) HLFLSO(HLF LSO) LSO(LSO) ETH(Ethereum) HLF(HyperLedger Fabric) OTHERS(Others) GLO --> MARCO MARCO --> ETHLSO MARCO --> HLFLSO MARCO --> LSO ETHLSO --> ETH HLFLSO --> HLF LSO --> OTHERS

GLO translation process

Supported operations

With MARCO, you can perform the following operations on any supported DLT using GLOS:

  • Transfer of native currency funds.
  • Call a method of a deployed smart contract.
  • Deploy a smart contract.

Specification

Versions

The GLO specification is subject to change to adapt to the constantly changing nature of ledger technologies. For this reason, the structure is versioned using Semantic Versioning.

The current version is 0.1.0.

GLO structure

GLOs are represented as JSON objects. The following is a list of the fields that are common to all GLOs:

FieldTypeDescription
versionstringRequired
Version of the GLO structure.
typeGenericLedgerBaseOperationType enumRequired
Type of operation to be performed on a given DLT network.
optionsGenericLedgerBaseOperationOptions objectRequired
Ledger-agnostic options of the operation.
metaGenericLedgerBaseOperationMeta objectLedger-specific options of the operation.

Example:

{ 
"version": "0.1.0",
"type": "transfer",
"options": {
"recipient": {
"lookup_service": {
"type": "ledger",
"value": "ethereum"
},
"resource": "0xfea8e07b145bb611a4b5ab5c015f3cc3644c083a"
},
"amount": 0
}
}

Data types

GenericLedgerBaseOperationType enum

List of supported GLO types:

  • transfer: Transfer of native currency funds.
  • contract_call: Method call of a deployed smart contract.
  • contract_deploy: Deployment of a smart contract.

GenericResourceLocator object

A resource locator object contains the information to retrieve wallets, smart contract template, or instance details from MARCO or DLT network.

This object has the following fields:

FieldTypeDescription
lookup_service.typestringRequired.
Lookup service to use.
Available values: marco, ledger.
lookup_service.valuestringRequired.
Specific lookup service. It varies depending on the type selected.
resourcestringRequired.
Resource identifier in the lookup service.
marco type

When lookup_service.type is set to marco, the lookup_service.value field must be set to marco.

The resource field is the MARCO platform's wallet, smart contract template, or instance identifier.

Example:

{
"lookup_service": {
"type": "marco",
"value": "marco"
},
"resource": "documentation-recipient-wallet-1"
}
ledger type

When lookup_service.type is ledger, the lookup_service.value field can be set to any of the following DLTs:

  • ethereum: Ethereum network.
  • hyperledger-fabric: Hyperledger Fabric network.
info

lookup_service.value must match the DLT where you want to execute the operation.

The field resource is the account or smart contract address in the DLT network.

Example:

{
"lookup_service": {
"type": "ledger",
"value": "ethereum"
},
"resource": "0xfea8e07b145bb611a4b5ab5c015f3cc3644c083a"
}

GenericLedgerBaseOperationOptions object

The body of the operation is generic for all ledger technologies MARCO supports. This object structure varies depending on the type of operation:

transfer options

An object representing the transfer GLO options.

FieldTypeDescription
recipientGenericResourceLocator objectRequired.
Resource locator of the recipient of the funds.
amountstring or numberRequired.
Amount of native currency to transfer to recipient.

Example:

{
"recipient": {
"lookup_service": {
"type": "ledger",
"value": "ethereum"
},
"resource": "0xfea8e07b145bb611a4b5ab5c015f3cc3644c083a"
},
"amount": 0
}
contract_call options

An object representing the contract_call GLO options.

FieldTypeDescription
contract_instanceGenericResourceLocator objectRequired.
Smart contract instance locator.
method_namestringRequired.
Method of the contract instance to be called.
argsList of stringsList of arguments passed to the method in the order defined.

Example:

{
"contract_instance": {
"lookup_service": {
"type": "ledger",
"value": "ethereum"
},
"resource": "0x8b0b7b8c7c7a4b2b4ab15c6d62a01a019b44b827"
},
"method_name": "set",
"args": ["0x1234567890123456789012345678901234567890", "0x1234567890123456789012345678901234567890"]
}
contract_deploy options

An object representing the contract_deploy GLO options.

FieldTypeDescription
contract_sourceGenericResourceLocator objectRequired.
Smart contract source locator.
argsList of stringsArguments used to initialise the contract.

Example:

{
"contract_source": {
"lookup_service": {
"type": "marco",
"value": "marco"
},
"resource": "documentation-contract-1:0.0.1"
},
"args": ["Hello World!"]
}

GenericLedgerBaseOperationMeta object

An object that is used to specify native ledger-specific options for an operation. Its content varies depending on the DLT being used.

For example, when using the Ethereum ledger, the native_transaction_content field can be used to specify options specific to Ethereum transactions, such as the gasPrice and gasLimit.

Example:

{
"ledger": {
"ethereum": {
"version": "0.0.1",
"native_transaction_content": {
"gasPrice": "0",
"gasLimit": "0"
}
}
}
}

If there is a conflict between the GenericLedgerBaseOperationOptions object and the GenericLedgerBaseOperationMeta object, the latter takes precedence.

Ethereum meta options

An object representing the specific metainformation for Ethereum operations.

Within the meta.ledger.ethereum.native_transaction_content field, the following options are available:

FieldTypeDescription
fromstring (hexadecimal)The Ethereum-native sender address that will be signing the transaction.
tostring (hexadecimal)The receiving Ethereum-native address.
datastringAn optional field to include arbitrary data.
chainIdnumber or string (hexadecimal)The id of the chain to prevent replay attacks. For more information, see EIP-155
noncestring (hexadecimal) or numberA sequentially incrementing counter which indicates the transaction number from the account
valuestring (hexadecimal) or numberThe amount of ether to transfer in WEI (the smallest denomination of ether).
gasPricestring (hexadecimal) or numberThe price per unit of gas in WEI that the sender is willing to pay.
gasLimitstring (hexadecimal) or numberThe maximum amount of gas that the sender is willing to spend on the transaction.

For more information, see Ethereum transactions.

Example:

{
"ledger": {
"ethereum": {
"version": "0.0.1",
"native_transaction_content": {
"from": "0x1234567890123456789012345678901234567890",
"to": "0x1234567890123456789012345678901234567890",
"data": "0x1234567890123456789012345678901234567890",
"chainId": 1,
"nonce": 0,
"value": 0,
"gasPrice": 0,
"gasLimit": 0
}
}
}
}

Examples

Transfer operation

Transfer operation using MARCO resolvable attribute documentation-recipient-wallet-1 on resource field. This operation transfers 66 native tokens to the address resolved. Since it is an Ethereum operation, it also sets the native attribute gasPrice to 0.

{ 
"version": "0.1.0",
"type": "transfer",
"options": {
"recipient": {
"lookup_service": {
"type": "marco",
"value": "marco"
},
"resource": "documentation-recipient-wallet-1"
},
"amount": 66
},
"meta": {
"ledger": {
"ethereum": {
"version": "0.0.1",
"native_transaction_content": {
"gasPrice": 0
}
}
}
}
}

Transfer operation using Ethereum's native attribute 0xfea8e07b145bb611a4b5ab5c015f3cc3644c083a on resource field.

{ 
"version": "0.1.0",
"type": "transfer",
"options": {
"recipient": {
"lookup_service": {
"type": "ledger",
"value": "ethereum"
},
"resource": "0xfea8e07b145bb611a4b5ab5c015f3cc3644c083a"
},
"amount": 0
}
}

Contract call operation

Contract call operation using MARCO resolvable attribute nft-contract on resource field. This operation calls the method mint of the contract with the argument my-nft.

{
"version":"0.1.0",
"type":"contract_call",
"options":{
"contract_instance":{
"lookup_service":{
"type":"marco",
"value":"marco"
},
"resource":"nft-contract"
},
"method_name":"mint",
"args":[
"my-nft"
]
},
"meta":{

}
}

Contract deploy operation

Contract deploy operation using MARCO resolvable attribute test-contract-message-registry:0.0.1 on resource field.

{ 
"version": "0.1.0",
"type": "contract_deploy",
"options": {
"contract_source": {
"lookup_service": {
"type": "marco",
"value": "marco"
},
"resource": "test-contract-message-registry:0.0.1"
},
},
"args": [
"Hello World!"
]
}

See also