Jump to: navigation, search

Client API

Warning: I found this page because a new contributor asked about it. As far as I can tell it was mostly written by someone who is not a developer and who has a repeated history of misrepresenting his crappy work as affiliated with Namecoin. I will be going through official channels to delete this page in the near future, but in the meantime assume that everything here is false, because you won't be far off. Cheers. --Biolizard89 (talk) 12:45, 30 January 2016 (UTC)

Namecoin Client API Specification

This document is a part of Namecoin Specification

WORKING DRAFT

This is a WORKING DRAFT it's not completed and it's not official in any way. It's not yet reviewed nor approved by Namecoin community.

Contents

Introduction

Namecoin Client API provides a way for other applications to query Namecoin identifiers, their associated data and do other actions involving Namecoin network and database.

Overview

Namecoin compliant daemons SHOULD implement Client API using JSON (see RFC 7159) and SHOULD implement all Namecoin commands mentioned in next sections. Daemons MAY implement additional commands and MAY use other data exchange formats besides JSON.

Namecoin specific commands

Required arguments are denoted inside < and > Optional arguments are inside [ and ].

Identifier Registration

name_firstupdate

Syntax:

name_firstupdate <identifier> <rand> [<tx>] <value>

Description: Register an identifier.

Wallet required: Yes

name_new

Syntax:

name_new <identifier>

Description: Pre-order an identifier.

Wallet required: Yes

name_update

Syntax:

name_update <identifier> <value> [<toaddress>]

Description: Update, transfer or renew identifier.

Wallet required: Yes

Identifier Lookup

name_filter

Syntax:

name_filter [regexp] [<maxage=36000>] [from=0] [nb=0] [stat]

Scan all identifiers in specified namespace which match regexp updated in last maxage blocks.

Wallet required: No

Examples:

  • list all unexpired domains: name_filter "d/"
  • list all domains: name_filter "d/" 0
  • list domains modified last 150 blocks: name_filter "d/" 150
  • count domains modified last 150 blocks: name_filter "d/" 150 0 0 stat
  • list 20 domains from number 100: name_filter "d/" 0 100 20
name_history

Syntax:

name_history <identifier>

Description: List all data values of an identifier.

Wallet required: No

name_list

Syntax:

name_list [<identifier>]

Description: List identifiers in a wallet.

Wallet required: Yes

name_scan

Syntax:

name_scan [<start-identifier>] [<max-return=500>]

Description: Scan all identifiers, starting at start-identifier and returning a maximum number of entries.

Wallet required: No

name_show

Syntax:

name_show <identifier>

Description: Returns a data for given identifier.

Wallet required: No


Namespace specific

domain_show

Syntax:

domain_show <domain> [field]

Description: Show associated data for specified domain, it MUST be fully qualified domain. When field is specified then return only data for that field.

Wallet required: No

Examples:

  • get data for specified domain: domain_show "api.namecoin.bit"
identity_show

Syntax:

identity_show <identity> [field]

Description: Show associated data for specified identity. When field is specified then return only data for that field.

Wallet required: No


Maintenance

name_clean

Syntax:

name_clean

Description: Remove firstupdates that cannot be satisfied and their dependents.

Clean unsatisfiable transactions from the wallet - including name_update on an already taken name. Wallet required: Yes


General commands

Control commands

getinfo

Syntax:

getinfo

Description: Returns an object containing various state info.

Wallet required: No

Result:

{
"version": xxxxx, (numeric) the server version
"protocolversion": xxxxx, (numeric) the protocol version
"walletversion": xxxxx, (numeric) the wallet version
"balance": xxxxxxx, (numeric) the total namecoin balance of the wallet
"blocks": xxxxxx, (numeric) the current number of blocks processed in the server
"timeoffset": xxxxx, (numeric) the time offset
"connections": xxxxx, (numeric) the number of connections
"proxy": "host:port", (string, optional) the proxy used by the server
"difficulty": xxxxxx, (numeric) the current difficulty
"testnet": true|false, (boolean) if the server is using testnet or not
"keypoololdest": xxxxxx, (numeric) the timestamp (seconds since GMT epoch) of the oldest pre-generated key in the key pool
"keypoolsize": xxxx, (numeric) how many new keys are pre-generated
"paytxfee": x.xxxx, (numeric) the transaction fee set in btc
"unlocked_until": ttt, (numeric) the timestamp in seconds since epoch (midnight Jan 1 1970 GMT) that the wallet is unlocked for transfers, or 0 if the wallet is locked
"errors": "..." (string) any error messages
}
help

Syntax:

help [<command>]

Description: List all commands, or get help for a specified command.

Wallet required: No

Arguments:

  1. "command" (string, optional) The command to get help on

Result: "text" (string) The help text

stop

Syntax:

stop

Description: Stop Namecoin server.

Wallet required: No

Network commands

addnode

Syntax:

addnode "node" "add|remove|onetry"

Description: Attempts add or remove a node from the addnode list. Or try a connection to a node once.

Wallet required: No

Arguments:

  1. "node" (string, required) The node (see getpeerinfo for nodes)
  2. "command" (string, required) 'add' to add a node to the list, 'remove' to remove a node from the list, 'onetry' to try a connection to the node once
getaddednodeinfo

Syntax:

getaddednodeinfo dns ( "node" )

Description: Returns information about the given added node, or all added nodes (note that onetry addnodes are not listed here) If dns is false, only a list of added nodes will be provided, otherwise connected information will also be available.

Wallet required: No

Arguments:

  1. dns (boolean, required) If false, only a list of added nodes will be provided, otherwise connected information will also be available.
  2. "node" (string, optional) If provided, return information about this specific node, otherwise all nodes are returned.

Result:

[
  {
    "addednode" : "192.168.0.201", (string) The node ip address
    "connected" : true|false, (boolean) If connected
    "addresses" : [
      {
        "address" : "192.168.0.201:8334", (string) The namecoin server host and port
        "connected" : "outbound" (string) connection, inbound or outbound
      }
      ,...
    ]
  }
  ,...
]
getconnectioncount

Syntax:

getconnectioncount

Description: Returns the number of connections to other nodes.

Wallet required: No

Result: n (numeric) The connection count

getnettotals

Syntax:

getnettotals

Description: Returns information about network traffic, including bytes in, bytes out, and current time.

Wallet required: No

Result:

{
"totalbytesrecv": n, (numeric) Total bytes received
"totalbytessent": n, (numeric) Total bytes sent
"timemillis": t (numeric) Total cpu time
}
getpeerinfo

Syntax:

getpeerinfo

Description: Returns data about each connected network node as a json array of objects.

Wallet required: No

Result:

[
  {
    "addr":"host:port", (string) The ip address and port of the peer
    "addrlocal":"ip:port", (string) local address
    "services":"00000001", (string) The services
    "lastsend": ttt, (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last send
    "lastrecv": ttt, (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last receive
    "bytessent": n, (numeric) The total bytes sent
    "bytesrecv": n, (numeric) The total bytes received
    "conntime": ttt, (numeric) The connection time in seconds since epoch (Jan 1 1970 GMT)
    "pingtime": n, (numeric) ping time
    "pingwait": n, (numeric) ping wait
    "version": v, (numeric) The peer version, such as 7001
    "subver": "/Satoshi:0.8.5/", (string) The string version
    "inbound": true|false, (boolean) Inbound (true) or Outbound (false)
    "startingheight": n, (numeric) The starting height (block) of the peer
    "banscore": n, (numeric) The ban score (stats.nMisbehavior)
    "syncnode" : true|false (booleamn) if sync node
  }
  ,...
}
ping

Syntax:

ping

Description: Requests that a ping be sent to all other nodes, to measure ping time. Results provided in getpeerinfo, pingtime and pingwait fields are decimal seconds. Ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping.

Wallet required: No

Blockchain

getbestblockhash
getblockcount
getblock
getblockhash
getdifficulty
getrawmempool
gettxout
gettxoutsetinfo
verifychain

Mining

getblocktemplate
getmininginfo
getnetworkhashps
submitblock

Raw transactions

createrawtransaction
decoderawtransaction
decodescript
getrawtransaction
sendrawtransaction
signrawtransaction

Utility

createmultisig
validateaddress
verifymessage

Wallet

addmultisigaddress
backupwallet
dumpprivkey
dumpwallet
encryptwallet
getaccountaddress
getaccount
getaddressesbyaccount
getbalance
getnewaddress
getrawchangeaddress
getreceivedbyaccount
getreceivedbyaddress
gettransaction
getunconfirmedbalance
getwalletinfo
importprivkey
importwallet
keypoolrefill
listaccounts
listaddressgroupings
listlockunspent
listreceivedbyaccount
listreceivedbyaddress
listsinceblock
listtransactions
listunspent
lockunspent
move
sendfrom
sendmany
sendtoaddress
setaccount
settxfee
signmessage
walletlock
walletpassphrasechange
walletpassphrase

Wallet-enabled mining

getgenerate
gethashespersec
getwork
setgenerate

References

[RFC7159] T. Bray, Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", March 2014 (TXT, HTML, PDF, XML)
[RFC3339] G. Klyne, C. Newman, "Date and Time on the Internet: Timestamps", July 2002 (TXT, HTML, PDF, XML)