TechDoc: ndau transactions and the ndau API¶
This technical documentation provides a detailed overview of ndau Transactions and the ndau API.
For more comprehensive information about ndau, please visit the ndau Knowledge Base.
For details on all ndau API Endpoints, please see the ndau API documentation on GitHub.
Transactions are submitted to and retrieved from the ndau blockchain through the ndau API: all transaction input and output data is in JSON format. When a transaction is committed a unique transaction hash is generated for it, and that hash can be used to query the API for the details of that transaction.
Data Types¶
| Data Type | Description |
|---|---|
| string | A string |
| int | An integer (in base 10) |
| duration | A period of time in microseconds (10-6 seconds) |
| napu | A quantity of ndau in napu (10-8 ndau) |
| nanocent | A quantity of USD in nanocents (10-11 US Dollars) |
| address | An account address in ndau text format |
| publickey | A secp256k1 or ed25519 public key in ndau text format |
| signature | A secp256k1 or ed25519 signature in ndau text format |
Some JSON fields are lists of parameters and are indicated with a [] prefix (such as []signatures). Fields specified as
lists must always be represented as lists even if they hold only a single value. Multiple values in a list are separated by commas.
To avoid rounding and precision errors created by different client environment, all ndau values are expressed as integers. There are never any floating point values in ndau transactions.
Submitting transactions¶
Each transaction is submitted in JSON format using the “json” fields shown below for each transaction. These names are longer and more descriptive than the compact format stored on the blockchain. Transactions may be prevalidated using the /tx/prevalidate/:txname endpoint before being submitted. Prevalidation ensures the transaction is valid and is properly signed, and it returns the transaction’s hash and any fees that will be charged for it when it is submitted. Any errors are indicated by an error code and a descriptive message. A valid transaction is submitted to the API with the /tx/submit/:txname endpoint.
Querying transactions¶
Transaction details can be retrieved by specifying the unique hash returned by the API when the transaction was submitted. Each transaction type returns a unique set of fields. In the descriptions below, the “msg” fields are the labels used for each field in the returned JSON. The transaction type is identified by the TransactableID field: these are the ID values associated with each transaction type.
1 Transfer
2 ChangeValidation
3 ReleaseFromEndowment
4 ChangeRecoursePeriod
5 Delegate
6 CreditEAI
7 Lock
8 Notify
9 SetRewardsDestination
10 SetValidation
11 Stake
12 RegisterNode
13 NominateNodeReward
14 ClaimNodeReward
15 TransferAndLock
16 CommandValidatorChange
18 UnregisterNode
19 Unstake
20 Issue
21 CreateChildAccount
22 RecordPrice
23 SetSysvar
24 SetStakeRules
25 RecordEndowmentNAV
26 ResolveStake
30 ChangeSchema
Mainnet and Testnet¶
The ndau mainnet and testnet are accessible to the public. Each node on each network is identified with a unique numeric ID (given as “0” here):
Mainnet: https://mainnet-0.ndau.tech:3030
Testnet: https://testnet-0.ndau.tech:3030
The ndau API is available on all nodes in either network.
Each transaction type returns a unique set of information. In the descriptions below, the “msg” fields are the labels used in the returned JSON
to identify each parameter. The “json” fields are the labels used for each parameter in the JSON input to the
/tx/submit and /tx/prevalidate endpoints.
Examples¶
Submittal¶
A transaction is submitted with an HTTP POST to /tx/submit/:txtype where :txtype is the name of the transaction type from the table above. The transaction JSON is submitted as described below. This example transfers 10 ndau from one account to another.
URL: https://mainnet-0.ndau.tech:3030/tx/submit/transfer
JSON:
{
"source": "ndak9vpyz58fjpa4kg6gei3p9nch8jbf9iyszhg8mw8ump7q",
"destination": "ndam5m7qpznkbczn8ewc39iqdd32gama785jkkrp3nxy9jre",
"qty": 1000000000,
"seq": 203,
"signatures": ["ayjaftcggbcaeib6ehzcwu7t85svchaj5kp6xhu5vmhrky25z7jfcwni3thp2evrrebcaz3vv5pn5hwtm5puecfj6w5s74iy64mji4wmawzefwxp5qbew9yjs56aqieb"]
}
Returns:
{
"fee_napu": 1000000,
"sib_napu": 0,
"err": "Err and ErrCode are only set if an error occurred",
"hash": "pAe0XAfcuiMwFlC4EQ8ftg",
"msg": "only set if additional information is available",
"code": 0
}
Query¶
A transaction query returns complete information about the transaction and information about the block on the ndau blockchain in which it is found. The transaction-specific information is in the TransactableID and Transactable fields. For example, using the transaction hash returned from the above transfer submittal:
URL: https://mainnet-0.ndau.tech:3030/transaction/pAe0XAfcuiMwFlC4EQ8ftg
Returns:
{
"BlockHeight": 13919,
"TxOffset": 0,
"Tx": {
"Nonce": "arqilpepEempMQJCrBEAAg==",
"TransactableID": 1,
"Transactable": {
"src": ["ndak9vpyz58fjpa4kg6gei3p9nch8jbf9iyszhg8mw8ump7q"],
"dst": ["ndam5m7qpznkbczn8ewc39iqdd32gama785jkkrp3nxy9jre"],
"qty": 1000000000,
"seq": 203,
"sig": [[2, "MEQCIDwh7ipLsfbhMRwJ2pvKnluazvVbG79SUVGIzE7cEm95AiBfM57azZ6RXtsiCKnlNw7pFuaWlGqLBS5C0q3bgkp+yQ=="]]
}
}
}
Because TxOffset is 0, the transaction is the first transaction in block 13919 on the ndau blockchain. TransactableID is 1, so it is a Transfer transaction.
Account management transactions¶
Transfer¶
Transfers ndau from one account to another. The source account must be unlocked and have a sufficient available balance to pay for the transfer and any fees. The destination account may be locked or unlocked but may not be in its unlock countdown period.
{
Source address `msg:"src" json:"source"`,
Destination address `msg:"dst" json:"destination"`,
Qty napu `msg:"qty" json:"qty"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
SetValidation¶
Establishes the initial validation rules (script and keys) for an account. This transaction is signed with the account’s ownership key.
{
Target address `msg:"tgt" json:"target"`,
Ownership publickey `msg:"own" json:"ownership"`,
ValidationKeys []publickey `msg:"key" json:"validation_keys"`,
ValidationScript string `msg:"val" json:"validation_script"`,
Sequence int `msg:"seq" json:"sequence"`,
Signature signature `msg:"sig" json:"signature"`
}
ChangeValidation¶
Changes the validation rules (script and keys) for an account.
{
Target address `msg:"tgt" json:"target"`,
NewKeys []publickey `msg:"key" json:"new_keys"`,
ValidationScript string `msg:"val" json:"validation_script"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Lock¶
Locks an account for the specified countdown period. Locked accounts may not be the source of Transfer transactions, but their balance
may be used to pay fees for other transactions.
{
Target address `msg:"tgt" json:"target"`,
Period duration `msg:"per" json:"period"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Notify¶
Gives notice to unlock an account. After the account’s countdown period expires, the account is unlocked. Accounts in their
countdown period may not be the source or destination of Transfer transactions.
{
Target address `msg:"tgt" json:"target"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Delegate¶
Delegates the responsibility for crediting account’s EAI to an active ndau network node. An account may be delegated or redelegated at any time, but does not earn EAI unless it is delegated.
{
Target address `msg:"tgt" json:"target"`,
Node address `msg:"nod" json:"node"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
ChangeRecoursePeriod¶
Changes the account’s recourse period, the time between a Transfer transaction and the addition of the transferred amount to
the destination account’s available balance.
{
Target address `msg:"tgt" json:"target"`,
Period duration `msg:"per" json:"period"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
SetRewardsDestination¶
Set the destination account for redirecting EAI and node rewards. If a rewards destination is not set, EAI and node rewards will be credited directly to the account earning them.
{
Target address `msg:"tgt" json:"target"`,
Destination address `msg:"dst" json:"destination"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
TransferAndLock¶
Transfers ndau to a newly-created account and locks it for the specified period. Its effect is identical to that of a
Transfer transaction followed by a Lock transaction from the destination account. The destination account may not exist on
the ndau blockchain prior to this transaction.
{
Source address `msg:"src" json:"source"`,
Destination address `msg:"dst" json:"destination"`,
Qty napu `msg:"qty" json:"qty"`,
Period duration `msg:"per" json:"period"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
CreateChildAccount¶
Creates a “child” account and specifies the account’s initial validation rules, recourse period, and the node delegated to credit the account’s EAI. Used to propagate the properties of special account types to newly-created accounts.
{
Target address `msg:"tgt" json:"target"`,
Child address `msg:"chd" json:"child"`,
ChildOwnership publickey `msg:"cown" json:"child_ownership"`,
ChildSignature signature `msg:"csig" json:"child_signature"`,
ChildRecoursePeriod duration `msg:"cper" json:"child_recourse_period"`,
ChildValidationKeys []publickey `msg:"ckey" json:"child_validation_keys"`,
ChildValidationScript string `msg:"cval" json:"child_validation_script"`,
ChildDelegationNode address `msg:"nod" json:"child_delegation_node"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Staking transactions¶
SetStakeRules¶
Defines a set of chaincode stake rules by associating them with a stake rules account.
{
Target address `msg:"tgt" json:"target"`,
StakeRules string `msg:"krs" json:"stake_rules"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Stake¶
Stakes ndau to a specified set of stake rules by either staking directly to a stake rules account (primary stake) or by staking to a primary stake account (co-stake).
{
Target address `msg:"tgt" json:"target"`,
Rules address `msg:"rul" json:"rules"`,
StakeTo address `msg:"sto" json:"stake_to"`,
Qty napu `msg:"qty" json:"qty"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Unstake¶
Revokes ndau previously staked. The right to unstake ndau is governed by the rules established in the stake rules account.
{
Target address `msg:"tgt" json:"target"`,
Rules address `msg:"rul" json:"rules"`,
StakeTo address `msg:"sto" json:"stake_to"`,
Qty napu `msg:"qty" json:"qty"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
ResolveStake¶
Resolves a stake by releasing all or part of it. Any portion (including all) of the stake may be burned instead of being
released back to the staking account. The amount released is unstaked: the staking account does not need to submit an Unstake
transaction. This transaction can only be submitted in accordance with the stake rules.
{
Target address `msg:"tgt" json:"target"`, primary staker
Rules address `msg:"rul" json:"rules"`,
Burn int `msg:"brn" json:"burn"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Node operations transactions¶
RegisterNode¶
Registers a node as an active node on the ndau blockchain, eligible to receive node rewards and to be promoted to a validator node. The node account must already be successfully staked to the node operations stake rules account.
{
Node address `msg:"nod" json:"node"`,
DistributionScript string `msg:"dis" json:"distribution_script"`,
Ownership publickey `msg:"own" json:"ownership"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
UnregisterNode¶
Removes an ndau network node from active status.
{
Node address `msg:"nod" json:"node"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
CreditEAI¶
Credits EAI to all accounts delegated to a node. This transaction is submitted by the registered node account.
{
Node address `msg:"nod" json:"node"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
ClaimNodeReward¶
Claims a node’s node reward after it has been nominated to receive it by a NominateNodeReward transaction.
The reward must be claimed by the active node within a short time period or it will be burned.
{
Node address `msg:"nod" json:"node"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
System transactions¶
ReleaseFromEndowment¶
Releases ndau from the Axiom Foundation Endowment. These new ndau are available to be issued into circulation, but are not yet in circulation or used in any ndau blockchain calculations.
This transaction is validated by the signature rules of the account specified in the
system variable ReleaseFromEndowmentAddress. That account pays the transaction fee.
{
Destination address `msg:"dst" json:"destination"`,
Qty napu `msg:"qty" json:"qty"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
Issue¶
Issues ndau previously released from the Axiom Foundation Endowment into circulation.
This transaction is validated by the signature rules of the account specified in the
system variable ReleaseFromEndowmentAddress. That account pays the transaction fee.
{
Qty napu `msg:"qty" json:"qty"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
RecordPrice¶
Records the current market price of ndau. This value is used to calculate whether SIB is in effect and, if so, what the current SIB fee is.
This transaction is validated by the signature rules of the account specified in the
system variable RecordPriceAddress. That account pays the transaction fee.
{
MarketPrice nanocent `msg:"prc" json:"market_price"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
NominateNodeReward¶
Nominates the node eligible to receive the currently-available node rewards. The nominated node must claim its reward within a short time period or it will be burned.
This transaction is validated by the signature rules of the account specified in the
system variable NominateNodeRewardAddress. That account pays the transaction fee.
{
Random int `msg:"rnd" json:"random"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
SetSysvar¶
Sets a system variable.
This transaction is validated by the signature rules of the account specified in the
system variable SetSysvarAddress. That account pays the transaction fee.
{
Name string `msg:"nme" json:"name"`,
Value string `msg:"vlu" json:"value"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
CommandValidatorChange¶
Changes a node’s “power”. All nodes with power greater than zero are part of the validator set.
This transaction is validated by the signature rules of the account specified in the
system variable CommandValidatorChangeAddress. That account pays the transaction fee.
{
Power int `msg:"pow" json:"power"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
ChangeSchema¶
Triggers an ndau node to shut down. Used to enable versioned upgrades which change the ndau blockchain’s database schema.
This transaction is validated by the signature rules of the account specified in the
system variable ChangeSchemaAddress. That account pays the transaction fee.
{
SchemaVersion string `msg:"sav" json:"schema_version"`,
Sequence int `msg:"seq" json:"sequence"`,
Signatures []signature `msg:"sig" json:"signatures"`
}
