Coin module API
Coin module architecture
Coin modules source codes (src folder) must be architectured as follow:
- api: exposed alpaca api that we treat in this document
- bridge (legacy): exposed ledger live api that we treat in “LL Blockchain integration” part
- logic: common logic that is shared between bridge and alpaca api interface
- network: coin module network dependencies and their model adapters, ideally we want an api abstraction layer
- test: it is where we store test-related files
- types
- signer: signer-related utils, if the usual SignerContext interface is not enough and requires an additional layer
Interface
The interface is defined in coin-framework library: ledger-live/libs/coin-framework/src/api/types.ts
The goal is to implement it in your context, and share code between bridge implementation and alpaca context (“logic” part on diagram)
Standard API methods
(Exact method signature can be found on the repo)
broadcast
Diffuse the user transaction (raw tx, hence string type) to the network via the node
combine
Combines the provided signature with its associated transaction (in native format). This function returns the representation of the signed transaction in the native format
craftTransaction
Crafts the user intent into an actual hex-encoded raw transaction, this is where we will translate what the user want into the real transaction
If user provides fees, it needs to override locally estimated fees
Integration test requirement:
- Send tx => crafted tx with corresponding amount and recipient
- Send max tx => crafted tx with max amount
estimateFees
Return an estimation of what user intent will cost on the network
Integration test requirement:
- Send tx fee estimation => No error, estimation value and other parameters higher than 0
getBalance
Returns all assets linked to the user (native, tokens, …)
Integration test requirement:
- Pristine account => native balance value at 0 expected
- Account with balance => native balance value higher than 0 expected
lastBlock
Return last block information (hash, time, height, …)
Integration test requirement:
- height => value higher than 0 expected
- hash => value matching right length
- time => value is a valid date
getBlockInfo
Return specific block information (hash, time, height, …)
Integration test requirement:
- height => value is the input height
- hash => value matching right length
- time => value is a valid date
listOperations
Returns operations on address related account. One operation is a movement of funds, so one blockchain transaction can trigger multiple operations (tracked via operationIndex)
Integration test requirement:
- list operations on a pristine account => empty array expected
- list operation on a standard account => atleast X operations (length
defined at test creation)
- check metadata of each kind of tx => IN, OUT, …
getBlock
Return specific block information (hash, time, height, …) and transactions
Integration test requirement:
- info.height => value is the height parameter
- info.hash => value matching right length
- info.time => value is a valid date
- transactions[].hash => value matching right length
- transactions[].fees => value higher than 0 expected
getStakes
Get staking positions owned by an address/account
Integration test requirement:
- items[].address => value matching right length
- items[].state => value is a valid state
- items[].amount => value greater than 0 expected, and equals amountDeposited + amountRewarded
- items[].amountDeposited => value greater than 0 expected
- items[].amountRewarded => value greater than 0 expected
getRewards
Get staking reward distribution events since address/account inception
Integration test requirement:
- items[].amount => value greater than 0 expected
- items[].createdAt => valid date expected
