[NXT] API 2 Brainstorming

[ferment]

We r planning to create other API. Old API will be called Legacy API and become obsolete. New API will be split to 2 parts - Low-level API and High-level API. If u r planning to write a client software u could start a thread to discuss what LL and HL API calls u need.

Before starting with APIs, here's what I understand to be the abstractions in NXT. I've tried to normalize the attributes as much as possible.

Abstractions

Block
- has many transactions
- has a generator account
- has a timestamp
- can be an orphan

Transaction
- has a type/subtype:
   Payment: subtypes: Ordinary Payment
   Messaging: subtypes: Arbitrary message, Alias assignment
   Colored coins: subtypes: Asset issuance, Asset transfer, Ask order placement, Bid order placement, Ask order cancel, Bid order cancel
- has a sender account
- has a recipient account
- has attachments
- has a timestamp
- has fee
- has amount
- has confirmations

Account
- has a secret phrase
- "created" in blockchain by receiving a transaction
- send transactions
- receive transactions
- generates blocks and receives fees (transparent forging)
- generates hallmarks/tokens
- balance defined by transactions and received block generation fees

Peer
- has an address
- has state: non-connected, connected, disconnected
- optionally hallmarked by an account

Alias
 -has a name and URI
 -assigned by a type of transaction using attachment
 -uri updated through a type of transaction using attachment

Asset
-assigned by a type of transaction using attachment?
[not released]

Arbitrary Message
-assigned by a type of transaction using attachment?
[not released]

Exchange
-has AskOrder
-has BidOrder
[not released]

So before brainstorming/designing an API, anything above incorrect?

Any more details on Asset, AM, Exchange, and TF attributes (deadline, etc)?

[1713967541]

1713967541

[1713967541]

1713967541

[Come-from-Beyond]

I'd like to add that everything can be done by using only one API - Low-level or High-level. Low-level requires a developer to understand internals of blockchain and transactions. High-level API is for casual programmers. They'll add a lot of overhead to server part, so the owner of a node may decide to switch High-level API support off.

[EmoneyRu]

Time from last block API request (add to getState)

Useful for stop-on-fork-chain monitoring

[Come-from-Beyond]

Low-level API won't have Accounts. This data is recovered via blockchain analysis.

[marcus03]

In the terminology of the v1 API:

• Unconfirmed transactions included in getAccountTransactionIds (or a second method for getting these)
• Include the next forging account as a return value of the getBlock and getState call
• Get the AliasID for an alias

That's all for now... :-)

[marcus03]

One more regarding orphan cleanup:

Right now my approach to clean up orphans on the client side would be like this:

• Make a list of all blocks ids
• Walk down the chain from the highest block and remove these blocks in the chain from my list
• The remaining blocks in the list would be the orphan blocks and would need to be deleted, together with their transactions

Is there a better approach? Like is there or could there been an API call that would return all block ids that NRS knows are orphans?

[ferment]

Low-level API won't have Accounts. This data is recovered via blockchain analysis.

Is that the same for AM, Alias, and Assets since they are just transaction types?

[Come-from-Beyond]

Low-level API won't have Accounts. This data is recovered via blockchain analysis.

Is that the same for AM, Alias, and Assets since they are just transaction types?

Yes. Low-level API will be just getBlock and getTransactions, maybe a few other requests.

[ferment]

Updated:

Block:
- Can be orphaned

Transaction types:
  Payment: subtypes: Ordinary Payment
  Messaging: subtypes: Arbitrary message, Alias assignment
  Colored coins: subtypes: Asset issuance, Asset transfer, Ask order placement, Bid order placement, Ask order cancel, Bid order cancel


Peer states: non-connected, connected, disconnected

[joefox]

reserved!

[ferment]

Low level API Ideas draft 1

Please note that I'm not super interested in exact names right now, but gathering functionality. I'll use existing names or similar.

My approach is to look at the 3 fundamental low level abstractions (block, transaction, and peer) and present APIs for handling CRUD type operations. For this pass, I'll leave out parameters and also specifics of return value (object vs id vs bytes).

NRS:
getVersion
getTime

Blocks:
getGenesisBlockDate
getLastBlock
getFirstBlock
getBlock
generateBlock
getOrphanBlocks
getNextGenerateTime/getNextGenerator (or something similar) - help?

Transactions:
createTransaction
getTransaction
getUnconfirmedTransactions
broadcastTransaction

Peers:
getPeers
getPeer
connectPeer
disconnectPeer
getLastFeedingPeer? (lastBlockchainFeeder)

With these calls, I think you can do everything essential.

What did I miss?

[Come-from-Beyond]

Ok, let's continue brainstorming.

[marcus03]

As you said - just brainstorming:

What takes most of the time is when my client updates from NRS is getting the updated confirmation counts for transactions with less than 720 confirmations, because there are lots of back and forth calls since you have to call getTransaction again and again over a lot of transactions.

Would be nice to have some kind of batch mode, so e.g. send me all transactions (or just the confirmations counts) that are in block x. Or block x to y. Or block x,y,z, etc. with just one request.

It's probably enough to just get the updated confirmations counts, not everything that is returned in getTransaction, since the rest stays the same.

[ferment]

High level API Ideas draft 1

Please note that I'm not super interested in exact names right now, but gathering functionality. I'll use existing names or similar.

NRS:
getState

Account:
getAccount
getAccountPublicKey
getBalance
encodeToken
decodeToken

Blocks:
getAccountGeneratedBlocks
getBlockTransactions
getNextBlock(current)
getPreviousBlock(current)
getBlocks(start, end)

Transactions:
getAccountTransactions - this is a mid-level call since it returns raw transactions.

Payments:
sendMoney (or sendPayment)
getPayment
getAccountPayments

Alias:
getAlias
getAliasByName
assignAlias
transferAlias
updateAlias (yes, I know its the same as assign, but hide that at high level)
getAccountAliases
searchAlias
searchAliasURI

Arbitrary Message:
The use of the term "message" is somewhat confusing in this context. Maybe just Document or Data?

getMessage
createMessage
updateMessage
getAccountMessages

Colored Coins:
*Need help here*

issueAsset
getAsset
getAssets
updateAsset
transferAsset
getAccountAssets

sendAsset
getAssetBalance
getAssetOwners

placeAskOrder
placeBidOrder
cancelAskOrder
cancelBidOrder
executeAskOrder (better verb?)
executeBidOrder (better verb?)

getAskOrder
getBidOrder
getAskOrders
getBidOrders
getAccountAskOrders
getAccountBidOrders
getAssetAskOrders
getAssetBidOrders
getLastAssetPrice

What did I miss?

[ferment]

On the low level side, it might be nice to have some kind of streaming api for blocks and transactions.

streamBlocks?
streamTransactions?

[ferment]

As you said - just brainstorming:

What takes most of the time is when my client updates from NRS is getting the updated confirmation counts for transactions with less than 720 confirmations, because there are lots of back and forth calls since you have to call getTransaction again and again over a lot of transactions.

Would be nice to have some kind of batch mode, so e.g. send me all transactions (or just the confirmations counts) that are in block x. Or block x to y. Or block x,y,z, etc. with just one request.

It's probably enough to just get the updated confirmations counts, not everything that is returned in getTransaction, since the rest stays the same.

Added getBlockTransactions to high level

[ferment]

One more regarding orphan cleanup:

Right now my approach to clean up orphans on the client side would be like this:

• Make a list of all blocks ids
• Walk down the chain from the highest block and remove these blocks in the chain from my list
• The remaining blocks in the list would be the orphan blocks and would need to be deleted, together with their transactions

Is there a better approach? Like is there or could there been an API call that would return all block ids that NRS knows are orphans?

Added getOrphanBlocks() to the low level.

[ferment]

While we're at high level stuff... how about some blockchain walking calls?

getNextBlock
getPreviousBlock

[Come-from-Beyond]

While we're at high level stuff... how about some blockchain walking calls?

getNextBlock
getPreviousBlock

How the server will know what the current block is?

[ferment]

While we're at high level stuff... how about some blockchain walking calls?

getNextBlock
getPreviousBlock

How the server will know what the current block is?

Pass it in. So you could walk with this pseudo code:

Code:

last = getLastBlock
while last
  last = getPreviousBlock(last)
end

next = getFirstBlock
while next
 next = getNextBlock(next)
end