Stellar API

Abstract

Using the Stellar API, a developer who is intereseted in this particular blockchain and has seen some of Rust language, can easily upload and deploy smart contracts both compiled and without compile. Vottun API is able to deploy and interact with it through a simple API Rest request, sending the name of the method and the parameters.

The API provides the developer with severall calls, but all of them are grouped in three main blocks:

Accounts: Allows to the developer to fund with testnet or futurnet tokens or to get the balance of a certain account.
Smart Contracts: Allows to the developer to upload, deploy and interact with a smart contract and get some infomation about it.
Query information: It is also possible to get some interesenting information such as the balance of an account, or the transaction information.

For using the API is necessary to sing up in Vottun World and access to the Stellar part of the Web3 API section. With this simple action your first account will be generated. To take full advantage of the APIs it is advisable to have some concepts about the Stellar network.

It is also important to consider that in order to maintain compatibility with the EVM section of the Vottun ecosystem, the following network identifiers have been established for the different Stellar networks:

Network name	Identifier
`testnet`	100000000
`futurnet`	100000001
`pubnet`	100000002

Endpoints

Fund account

This endpoint is usefull to fund accounts in testnet or futurnet. To fund an account in pubnet is necessary to do a current transaction of lumens between two accounts

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/account/fund

Request

The request must include a json body with the following fields:

name	type	required	description	example
`account`	string	yes	The we want to fund	GBDZZEECOXDNP5DYVVLQEV4DHX4ODZ...2YFLO7XRWL5D47AF656JB
`networkId`	int	yes	The network identificator	100000001

Example

{
    "account": "GBDZZEECOXDNP5DYVVLQEV4DHX4ODZ...2YFLO7XRWL5D47AF656JB",
    "networkId": 100000001
}

Http status

result	http status
The account has been succesfully funded	201
The account already funded to starting balance	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Get account balance

This endpoint is usefull to get the account balance in the desired network.

The call to be executed is:

GET https://api.vottun.tech/stellar/v1/account/balance

Request

The request must include a json body with the following fields:

name	type	required	description	example
`account`	string	yes	The we want to fund	GBDZZEECOXDNP5DYVVLQEV4DHX4OD...YFLO7XRWL5D47AF656JB
`networkId`	int	yes	The network identificator	100000001

Example

{
    "account": "GBDZZEECOXDNP5DYVVLQEV4DHX4ODZ...2YFLO7XRWL5D47AF656JB",
    "networkId": 100000001
}

Response

It will return a json with the id assinged to the contract in the platform:

name	type	description	example
`balance`	int	The balance of the specified account	10000

Example

{
    "balance": 10000
}

Http status

result	http status
The account has been succesfully funded	201
The account already funded to starting balance	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Save a Smart Contract

Thanks to this endpoint you can attach to the Vottun ecosystem the contract you have worked on to finally exploit it with your dApp.

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/contract/save

Request

The request must include body with the following data form-data format.

name	type	required	description	example
`file`	file	yes	The result .wasm file after compile the contract	helloWorld.wasm
`name`	string	yes	A name to indentify the contract	helloWorld
`description`	string	no	Text to describe what the contract do	This is an easy contract to check functionallity

Response

It will return a json with the id assinged to the contract in the platform:

name	type	description	example
`id`	int	The specs id assigned to contract	12345

Example

{
    "id": 12226
}

Http status

result	http status
The smart contract has been inserted succesfully	201
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Upload a project

This endpoint allows us to upload one or more contracts where you have been working on. Using this endpoint we will compile the contract for you. We only need a zip file with all the contect of you working directory. It is important to compress the content of your working directory not the directory itself.

After you get the correct answer, the compilation process has been launched and there is other endpoint to check the compilation status of a certain contract.

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/contract/upload

Request

The request must include body with the following data if a form-data.

name	type	required	description	example
`file`	file	yes	The result .wasm file after compile the contract	helloWorld.wasm

Response

The upload method will answer with the generated name of the file and an array with the detected different contracts in the project.

name	type	description	example
`filename`	string	A unique filename of the uploaded project	increment
`contracts`	[]string	An array with the names of the different contracts detected in the project	[]

Example

{
    "filename": "increment4568",
    "contracts": [
        "hello-world",
        "soroban-increment-contract"
    ]
}

Http status

result	http status
The project has been inserted succesfully uploaded	201
The uploaded file is not a Cargo project. The zip file contains the folder not the contents	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Deploy contract

This endpoint allows us to deploy one contract in our desired network. We can choose between testnet, futurenet and mainnet. The smart contract must be previously uploaded to the platform as its identifier must be informed in the contractSpecsId field. Its execution will return the address of the contract and the hash transaction.

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/contract/deployment

Request

The request must include a json body with the following fields:

name	type	required	description	example
`contractSpecsId`	int	yes	Contract Specs ID. Is the id of the contract deployed in the Core Platform	3
`myReference`	string	no	Customer reference. It is used to retrieve information about the request if a problem occurs during the request. It is better to use different one for each request but if it is repeated there will not raise any error	REF0008A5F
`blockchainNetwork`	int	yes	The chain id	100000000

Example

{
    "contractSpecsId": 12228,
    "myReference":"testing",
    "blockchainNetwork":100000000
}

Response

It will return a json with the following fields (the transaction is not still confirmed):

name	type	description	example
`address`	string	The contract Address	CBSI5T7EN3HZJZBMR3SBHZIHKZFM...2OPT7T2H4GFWZJ3YKFHS5GUH
`salt`	string	The Id of the Soroban contract	00wHpaHN9f
`status`	string	The status of the deployment	PENDING
`txHash`	string	The transaction Hash	ecc92cf47e48c35e799b59395064df...be3936bb74df95f5efa688c290d

Example

{
    "address": "CBSI5T7EN3HZJZBMR3SBHZIHKZF...K2OPT7T2H4GFWZJ3YKFHS5GUH",
    "salt": "00wHpaHN9f",
    "status": "PENDING",
    "txHash": "ecc92cf47e48c35e799b59395064df2...63be3936bb74df95f5efa688c290d"
}

Http status

result	http status
The contract deployment has been succesfully started	201
The specified contract specs id does not exist	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Estimate Deploy contract

This endpoint allows us to make an estimation of the cost of a deployment of the specified contract in the desired network. We can choose between testnet, futurenet and mainnet. The smart contract must be previously uploaded to the platform as its identifier must be informed in the contractSpecsId field.

The answer apart from the cost will tell us if it is necessary to restore the contract because the TTL (time to live) has come to end. If it is true will provide the cost of restore it

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/contract/deployment/estimate

Request

The request must include a json body with the following fields:

name	type	required	description	example
`contractSpecsId`	int	yes	Contract Specs ID. Is the id of the contract deployed in the Core Platform	3
`blockchainNetwork`	int	yes	The chain id	100000000

Example

{
    "contractSpecsId": 12228,
    "blockchainNetwork":100000000
}

Response

It will return a json with the following fields (the transaction is not still confirmed):

name	type	description	example
`estimatedCost`	float	The estimated cost in lumens of the deployment of the contract	0.1287435
`restore`	boolean	It is necessary to extend the TTL of the contract or not	false
`restoreCost`	float	If restore is true it will be informed the cost of extend the TTL	0

Example

{
    "estimatedCost": 0.1287435,
    "restore": false,
    "restoreCost": 0
}

Http status

result	http status
The contract deployment estimation has been correctely calculated	201
The specified contract specs id does not exist	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Invoke contract

This endpoint allows us to invoke any method of a deployed contract. As discussed in the abstract, you need to know both the name of the function and its parameters in the right order. You can also check the detail section of the contract you deployed in your Vottun World account to know the exact name of the method and the parameters names, types and order you have to send in the request.

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/contract/invoke

Request

The request must include a json body with the following fields:

name	type	required	description	example
`blockchainNetwork`	int	yes	The chain id	100000000
`myReference`	string	no	The reference we inform in the deployment	myReference
`restore`	boolean	yes	A flag that indicates if you want to extend the TTL	false
`address`	string	yes	It is the contract on which the transaction is to be executed.	CAOUQSKD6CBFCHCM...J33YIF7KTASLDSZ27MDB
`method`	string	yes	The smart contract method as it is written in the Rust code	initialize
`params`	[]any	yes	It is an array with all the parameters required by the smart contract method is going to be executed. The order is important	[18,"Vottun","VTN"]

Example

{
    "blockchainNetwork":0,
    "myReference":"testToken",
    "restore": false,
    "address": "CAOUQSKD6CBFCHCMAFBQNKLLUGYL5PD5X5E2J33YIF7KTASLDSZ27MDB",
    "method": "initialize",
    "params":[
        "GDPXQZGKPR4IGUZFUJOXF5UFCPN424AG2WD2GJ2MRV3W34XZI5IA7XEB",
        18,
        "Vottun",
        "VTN"
    ]    
}

Response

It will return a json with the following fields (the transaction is not still confirmed):

name	type	description	example
`txHash`	string	The transaction hash of the invokation of the contract	661b9e39e7e44c75782a7313cfacdaa2...f7b5152ecb024443f3cc0290170de
`status`	string	Is the status in which is the transaction	PENDING

Example

{
    "txHash": "661b9e39e7e44c75782a7313cfacdaa2...f7b5152ecb024443f3cc0290170de",
    "status": "PENDING"
}

Http status

result	http status
The contract invokation has been correctely done	200
The specified contract instance id does not exist or the parameters are incorrect	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Estimate Invoke contract

This endpoint allows us to estimate the cost of the invokation of any method of a contract.

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/contract/invoke/estimate

Request

The request must include a json body with the following fields:

name	type	required	description	example
`blockchainNetwork`	int	yes	The chain id	100000000
`myReference`	string	no	The reference we inform in the deployment	myReference
`restore`	boolean	yes	A flag that indicates if you want to extend the TTL	false
`address`	string	yes	It is the contract on which the transaction is to be executed.	CAOUQSKD6CBFCHCM...J33YIF7KTASLDSZ27MDB
`method`	string	yes	The smart contract method as it is written in the Rust code	initialize
`params`	[]any	yes	It is an array with all the parameters required by the smart contract method is going to be executed. The order is important	[18,"Vottun","VTN"]

Example

{
    "blockchainNetwork":0,
    "myReference":"testToken",
    "restore": false,
    "address": "CAOUQSKD6CBFCHCMAFBQNKLLUGYL5PD5X5E2J33YIF7KTASLDSZ27MDB",
    "method": "initialize",
    "params":[
        "GDPXQZGKPR4IGUZFUJOXF5UFCPN424AG2WD2GJ2MRV3W34XZI5IA7XEB",
        18,
        "Vottun",
        "VTN"
    ]    
}

Response

It will return a json with the following fields (the transaction is not still confirmed):

name	type	description	example
`estimatedCost`	float	The estimated cost in lumens of the deployment of the contract	0.1287435
`restore`	boolean	It is necessary to extend the TTL of the contract or not	false
`restoreCost`	float	If restore is true it will be informed the cost of extend the TTL	0

Example

{
    "estimatedCost": 0.1287435,
    "restore": false,
    "restoreCost": 0
}

Http status

result	http status
The contract deployment estimation has been correctely calculated	201
The specified contract specs id does not exist	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Extend contract

In the Stellar blockchain network, TTL (Time To Live) refers to the lifespan of a transaction. Specifically, it is the maximum amount of time a transaction can remain valid before it is considered expired and is no longer processed by the network.

This endpoint is valid for extend the time of a transaction remains valid.

The call to be executed is:

POST https://api.vottun.tech/stellar/v1/contract/invoke/extendttl

Request

The request must include a json body with the following fields:

name	type	required	description	example
`blockchainNetwork`	int	yes	The chain id	100000000
`address`	string	yes	The contract address we want to extend	myReference
`extend_to`	boolean	yes	The number of blocks you want to extend the instance live	false

Example

{
    "blockchainNetwork": 100000000,
    "address": "CDX2LWXTVGG3SOTNI7AHI4SKYVYCUHYRE4YXZNHUBR7QY4PZQC46KR7L",
    "extend_to":2531500
}

Response

It will return a json with the following fields (the transaction is not still confirmed):

name	type	description	example
`txHash`	string	The transaction hash of the invokation of the contract	661b9e39e7e44c75782a7313cfacdaa2...f7b5152ecb024443f3cc0290170de
`status`	string	Is the status in which is the transaction	PENDING

Example

{
    "txHash": "574b6b392ebf599204638ffa5ededab...8ba7b51c9ac698eb32ac679d068ec3",
    "status": "SUCCESS"
}

Http status

result	http status
The contract invokation has been correctely done	200
The specified contract instance id does not exist or the parameters are incorrect	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Get contract methods

Using this endpoint is possible to get all the methods of a contract, the names and types of its arguments and the returned type.

The call to be executed is:

GET https://api.vottun.tech/stellar/v1/contract/{contractId}/methods

Path Params

name	type	required	description	example
`contractId`	int	yes	The specs id of the contract.	12202

The request must include a json body with the following fields:

name	type	required	description	example
`blockchainNetwork`	int	yes	The chain id	100000000

Example

{
    "blockchainNetwork":100000000
}

Response

It will return a json with a array of the strings correspondig to each mehod:

name	type	description	example
`methods`	[]string	The name of the method, the argruments and the returning type	fn allowance(from: Address, spender: Address) -> i128

Example

{
    "methods": [
        "fn allowance(from: Address, spender: Address) -> i128",
        "fn approve(from: Address, spender: Address, amount: i128, expiration_ledger: u32)",
        "fn balance(id: Address) -> i128",
        "fn burn(from: Address, amount: i128)",
        "fn burn_from(spender: Address, from: Address, amount: i128)",
        "fn decimals() -> u32",
        "fn initialize(admin: Address, decimal: u32, name: string, symbol: string)",
        "fn mint(to: Address, amount: i128)",
        "fn name() -> string",
        "fn set_admin(new_admin: Address)",
        "fn symbol() -> string",
        "fn transfer(from: Address, to: Address, amount: i128)",
        "fn transfer_from(spender: Address, from: Address, to: Address, amount: i128)"
    ]
}

Http status

result	http status
The contract methods correctely achived	200
The specified contract instance id does not exist	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Get contract TTL info

This enpoint is valid to know if a installed contract is alive or not.

The call to be executed is:

GET https://api.vottun.tech/stellar/v1/contract/{contractId}/contracttl

Path Params

name	type	required	description	example
`contractId`	int	yes	The specs id of the contract.	12202

The request must include a json body with the following fields:

name	type	required	description	example
`blockchainNetwork`	int	yes	The chain id	100000000

Example

{
    "blockchainNetwork":100000000
}

Response

It will return a json object with the status of the contract:

name	type	description	example
`isAlive`	boolean	The contract is alive or not	true

Example

{
    "isAlive": true
}

Http status

result	http status
The contract status correctely achived	200
The specified contract id does not exist in the specified network	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Get contract instance TTL info

This endpoint is valid to know if a particular instance of a contract is alive or not and until which leadger is going to be alive.

The call to be executed is:

GET https://api.vottun.tech/stellar/v1/contract/{address}/instancettl

Path Params

name	type	required	description	example
`address`	int	yes	The contract instance address.	CBCBJ3N4TD6IA22VXNAP...H3OSM2HQEPLX2LTHIUZL

The request must include a json body with the following fields:

name	type	required	description	example
`blockchainNetwork`	int	yes	The chain id	100000000
`sourceAccount`	string	yes	The account of the sender of the request	GAXVGRJ65MPK33...KJNLYXBCZLDGX4MPBR4LRHBHS

Example

{
    "blockchainNetwork":100000000,
    "sourceAccount":"GAXVGRJ65MPW47CLPK33TNGW5XJBAR7KJNLYXBCZLDGX4MPBR4LRHBHS"
}

Response

It will return a json object with the status of the contract:

name	type	description	example
`isAlive`	boolean	The contract is alive or not	true
`latestLedger`	int	The latest ledger number introduced in the network	458449
`liveUntilLedger`	int	The ledger number until the instance is going to be alive	2315175

Example

{
    "isAlive": true,
    "latestLedger": 458449,
    "liveUntilLedger": 2315175
}

Http status

result	http status
The contract status correctely achived	200
The specified contract instance address or the source account does not exist in the specified network	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Get transaction information

Using this enpoint you will achive information about any transaction

The call to be executed is:

GET https://api.vottun.tech/stellar/v1/transaction/{txHash}/info?network=100000000

Path Params

name	type	required	description	example
`txHash`	string	yes	The transaction Hash	574b6b392ebf599204638ffa5..48ba7b51c9ac698eb32ac679d068ec3

Query Params

name	type	required	description	example
`network`	int	yes	It identifies the blockchain network where the transaction was inserted.	100000000

Response

The call will return the following json object with the blockchain transaction information.

name	type	description	example
`network`	int	The network identifier	1
`status`	string	The status of the transaction	SUCCESS
`transaction.source_account`	string	The sender of the transaction	GBINWTXKQG2YCP3REEVEFYPN...4VI5XHLHN3MU5Q
`transaction.sequence_number`	int	The order of transactions of an account	1037530954727427
`transaction.max_fee`	int	Maximun fee can be charged	795806
`transaction.operations`	any	Actions the transaction executes	`{"extendTo": 2531500}`
`transaction.memo`	string	Additional information	Tokens transfer
`receipt.code`	string	Result of the operation
`receipt.fee_charged`	int	Transaction fees	661367
`receipt.ledger`	int	The ledger number	457918
`receipt.createdAt`	string	Confirmation timestamp	2024-10-15T13:41:12Z
`receipt.return_value`	boolean	Produces a return value	false
`receipt.events`	any	Triggered events
`error`	any	Errors if exist

Example

{
    "network": 100000000,
    "status": "SUCCESS",
    "transaction": {
        "source_account": "GBINWTXKQG2YCP3REEVEFYPNFDRAE4VI5XHBX5RGNQLHN3MU5QRLVQYD",
        "sequence_number": 1037530954727427,
        "max_fee": 795806,
        "operations": {
            "extendTo": 2531500
        },
        "memo": null
    },
    "recipt": {
        "code": "",
        "fee_charged": 661367,
        "ledger": 457918,
        "createdAt": "2024-10-15T13:41:12Z",
        "return_value": false,
        "events": null
    },
    "error": ""
}

Http status

result	http status
The tx information has succesfully achived	200
The specified contract transaction hash or network are incorrect	400
The customer is not authorized	401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)	503

Abstract​

Endpoints​

Fund account​

Get account balance​

Save a Smart Contract​

Upload a project​

Deploy contract​

Estimate Deploy contract​

Invoke contract​

Estimate Invoke contract​

Extend contract​

Get contract methods​

Get contract TTL info​

Get contract instance TTL info​

Get transaction information​

Abstract

Endpoints

Fund account

Get account balance

Save a Smart Contract

Upload a project

Deploy contract

Estimate Deploy contract

Invoke contract

Estimate Invoke contract

Extend contract

Get contract methods

Get contract TTL info

Get contract instance TTL info

Get transaction information