ARCHIVE/xahau.js
1
0
Fork 0
mirror of https://github.com/Xahau/xahau.js.git synced 2025-11-19 11:45:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #621 from clark800/schemas

Browse Source 
Fix and reorganize schemas and switch to ajv validator
This commit is contained in:
Geert Weening
2015-11-02 21:34:01 +01:00
parent 7c1831ef38 c7b021c7be
commit 90c928205a
226 changed files with 179 additions and 8590 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/BUILD.md
View File

@@ -1,20 +0,0 @@
Using Flow typechecking
=======================
Stage 1
-------
1. Add /* @flow */ to the top of a file you want to typecheck
2. Run `gulp typecheck` to generate a list of warnings
Stage 2
-------
When all source files have the /* @flow */ header and all warnings have been
addressed, remove the `weak: true` option from Gulpfile.js, run
`gulp typecheck` and remove all the additional warnings.
Stage 3
-------
Add type annotations to the source code and run `gulp strip` to strip
the type annotations and write the output to the `out` directory. After
type annotations are added, the program must be run from the `out` directory
because Node does not understand the annotations

252
docs/GUIDES.md
View File

@@ -1,252 +0,0 @@
#Guides
This file provides step-by-step walkthroughs for some of the most common usages of `ripple-lib`.
###In this document
1. [Connecting to the Ripple network with `Remote`](GUIDES.md#connecting-to-the-ripple-network)
2. [Using `Remote` functions and `Request` objects](GUIDES.md#sending-rippled-API-requests)
3. [Listening to the network](GUIDES.md#listening-to-the-network)
4. [Submitting a payment to the network](GUIDES.md#submitting-a-payment-to-the-network)
* [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees)
5. [Submitting a trade offer to the network](GUIDES.md#submitting-a-trade-offer-to-the-network)
###Also see
1. [The ripple-lib README](../README.md)
2. [The ripple-lib API Reference](REFERENCE.md)
##Connecting to the Ripple network
1. [Get ripple-lib](../README.md#installation)
2. Load the ripple-lib module into a Node.js file or webpage:
```js
/* Loading ripple-lib with Node.js */
var Remote = require('ripple-lib').Remote;
/* Loading ripple-lib in a webpage */
// var Remote = ripple.Remote;
```
3. Create a new `Remote` and connect to the network:
```js
var options = {
trace : false,
trusted: true,
local_signing: true,
servers: [
{ host: 's-west.ripple.com', port: 443, secure: true }
]
};
var remote = new Remote(options);
remote.connect(function(err, res) {
/* remote connected, use some remote functions here */
});
```
__NOTE:__ See the API Reference for available [`Remote` options](REFERENCE.md#1-remote-options)
4. You're connected! Read on to see what to do now.
##Generating a new Ripple Wallet
```js
var ripple = require('ripple-lib');
// subscribing to a server allows for more entropy
var remote = new ripple.Remote({
servers: [
{ host: 's1.ripple.com', port: 443, secure: true }
]
});
remote.connect(function(err, res) {
/* remote connected */
});
// Wait for randomness to have been added.
// The entropy of the random generator is increased
// by random data received from a rippled
remote.once('random', function(err, info) {
var wallet = ripple.Wallet.generate();
console.log(wallet);
// { address: 'rEf4sbVobiiDGExrNj2PkNHGMA8eS6jWh3',
// secret: 'shFh4a38EZpEdZxrLifEnVPAoBRce' }
});
```
##Sending rippled API requests
`Remote` contains functions for constructing a `Request` object.
A `Request` is an `EventEmitter` so you can listen for success or failure events -- or, instead, you can provide a callback.
Here is an example, using [requestServerInfo](https://ripple.com/wiki/JSON_Messages#server_info).
+ Constructing a `Request` with event listeners
```js
var request = remote.requestServerInfo();
request.on('success', function onSuccess(res) {
//handle success
});
request.on('error', function onError(err) {
//handle error
});
request.request();
```
+ Using a callback:
```js
remote.request('server_info', function(err, res) {
if (err) {
//handle error
} else {
//handle success
}
});
```
__NOTE:__ See the API Reference for available [`Remote` functions](REFERENCE.md#2-remote-functions)
##Listening to the network
See the [wiki](https://ripple.com/wiki/JSON_Messages#subscribe) for details on subscription requests.
```js
/* Loading ripple-lib with Node.js */
var Remote = require('ripple-lib').Remote;
/* Loading ripple-lib in a webpage */
// var Remote = ripple.Remote;
var remote = new Remote({options});
remote.connect(function() {
var remote = new Remote({
// see the API Reference for available options
servers: [ 'wss://s1.ripple.com:443' ]
});
remote.connect(function() {
console.log('Remote connected');
var streams = [
'ledger',
'transactions'
];
var request = remote.requestSubscribe(streams);
request.on('error', function(error) {
console.log('request error: ', error);
});
// the `ledger_closed` and `transaction` will come in on the remote
// since the request for subscribe is finalized after the success return
// the streaming events will still come in, but not on the initial request
remote.on('ledger_closed', function(ledger) {
console.log('ledger_closed: ', JSON.stringify(ledger, null, 2));
});
remote.on('transaction', function(transaction) {
console.log('transaction: ', JSON.stringify(transaction, null, 2));
});
remote.on('error', function(error) {
console.log('remote error: ', error);
});
// fire the request
request.request();
});
});
```
* https://ripple.com/wiki/RPC_API#transactions_stream_messages
* https://ripple.com/wiki/RPC_API#ledger_stream_messages
##Submitting a payment to the network
Submitting a payment transaction to the Ripple network involves connecting to a `Remote`, creating a transaction, signing it with the user's secret, and submitting it to the `rippled` server. Note that the `Amount` module is used to convert human-readable amounts like '1 XRP' or '10.50 USD' to the type of Amount object used by the Ripple network.
```js
/* Loading ripple-lib Remote and Amount modules in Node.js */
var Remote = require('ripple-lib').Remote;
var Amount = require('ripple-lib').Amount;
/* Loading ripple-lib Remote and Amount modules in a webpage */
// var Remote = ripple.Remote;
// var Amount = ripple.Amount;
var MY_ADDRESS = 'rrrMyAddress';
var MY_SECRET = 'secret';
var RECIPIENT = 'rrrRecipient';
var AMOUNT = Amount.from_human('1 USD').set_issuer('rrrIssuer');
var remote = new Remote({ /* Remote options */ });
remote.connect(function() {
remote.setSecret(MY_ADDRESS, MY_SECRET);
var transaction = remote.createTransaction('Payment', {
account: MY_ADDRESS,
destination: RECIPIENT,
amount: AMOUNT
});
transaction.submit(function(err, res) {
/* handle submission errors / success */
});
});
```
###A note on transaction fees
A full description of network transaction fees can be found on the [Ripple Wiki](https://ripple.com/wiki/Transaction_Fee).
In short, transaction fees are very small amounts (on the order of ~10) of [XRP drops](https://ripple.com/wiki/Ripple_credits#Notes_on_drops) spent and destroyed with every transaction. They are largely used to account for network load and prevent spam. With `ripple-lib`, transaction fees are calculated locally by default and the fee you are willing to pay is submitted along with your transaction.
Since the fee required for a transaction may change between the time when the original fee was calculated and the time when the transaction is submitted, it is wise to use the [`fee_cushion`](REFERENCE.md#1-remote-options) to ensure that the transaction will go through. For example, suppose the original fee calculated for a transaction was 10 XRP drops but at the instant the transaction is submitted the server is experiencing a higher load and it has raised its minimum fee to 12 XRP drops. Without a `fee_cusion`, this transaction would not be processed by the server, but with a `fee_cusion` of, say, 1.5 it would be processed and you would just pay the 2 extra XRP drops.
The [`max_fee`](REFERENCE.md#1-remote-options) option can be used to avoid submitting a transaction to a server that is charging unreasonably high fees.
##Submitting a trade offer to the network
Submitting a trade offer to the network is similar to submitting a payment transaction. Here is an example offering to sell 1 USD in exchange for 100 XRP:
```js
/* Loading ripple-lib Remote and Amount modules in Node.js */
var Remote = require('ripple-lib').Remote;
var Amount = require('ripple-lib').Amount;
/* Loading ripple-lib Remote and Amount modules in a webpage */
// var Remote = ripple.Remote;
// var Amount = ripple.Amount;
var MY_ADDRESS = 'rrrMyAddress';
var MY_SECRET = 'secret';
var GATEWAY = 'rrrGateWay';
var remote = new Remote({ /* Remote options */ });
remote.connect(function() {
remote.setSecret(MY_ADDRESS, MY_SECRET);
var transaction = remote.createTransaction('OfferCreate', {
account: MY_ADDRESS,
taker_pays: '100',
taker_gets: '1/USD/' + GATEWAY
});
transaction.submit(function(err, res) {
/* handle submission errors / success */
});
});
```

376
docs/REFERENCE.md
View File

@@ -1,376 +0,0 @@
#API Reference
__(More examples coming soon!)__
###In this document:
1. [`Remote` options](REFERENCE.md#remote-options)
2. [`Request` constructors](REFERENCE.md#request-constructor-functions)
+ [Server requests](REFERENCE.md#server-requests)
+ [Ledger requests](REFERENCE.md#ledger-requests)
+ [Transaction requests](REFERENCE.md#transaction-requests)
+ [Account requests](REFERENCE.md#account-requests)
+ [Orderbook requests](REFERENCE.md#orderbook-requests)
+ [Transaction requests](REFERENCE.md#transaction-requests)
3. [`Transaction` constructors](REFERENCE.md#transaction-constructors)
+ [Transaction events](REFERENCE.md#transaction-events)
4. [Subscriptions](REFERENCE.md#subscriptions)
+ [Orderbook subscription](REFERENCE.md#orderbook-subscription)
###Also see:
1. [The ripple-lib README](../README.md)
2. [The ripple-lib GUIDES](GUIDES.md)a
#Remote options
```js
/* Loading ripple-lib with Node.js */
var Remote = require('ripple-lib').Remote;
/* Loading ripple-lib in a webpage */
// var Remote = ripple.Remote;
var options = { };
var remote = new Remote(options);
```
A new `Remote` can be created with the following options:
+ `trace` *boolean default: false* Log all of the events emitted
+ `max_listeners` *number default: 0* Set maxListeners for servers
+ `trusted` *boolean default: false*, if remote is trusted (boolean)
+ `local_signing` *boolean default: true*
+ `local_fee` *boolean default: true* Set whether the transaction fee range will be set locally, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees))
+ `fee_cushion` *number default: 1.2* Extra fee multiplier to account for async fee changes, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees))
+ `max_fee` *number default: Infinity* Maximum acceptable transaction fee, see [A note on transaction fees](GUIDES.md#a-note-on-transaction-fees)
+ `servers` *array* Array of server objects of the following form:
```js
{
host: <string>,
port: <number>,
secure: <boolean>
}
```
or
```js
'wss://host:port'
```
#Request constructor functions
Some requests have helper methods to construct the requests object and set properties on the message object. These will often be the more used requests and the helper methods is the preferred way of constructing these requests.
Other request can still be made, but the type will have to be passed in directly to request constructor. See examples below.
If the method is camelCased and starts with `request`, it's a helper method that wraps the request constructor.
##Server requests
**[requestServerInfo([callback])](https://ripple.com/wiki/JSON_Messages#server_info)**
Returns information about the state of the server. If you are connected to multiple servers and want to select by a particular host, use `request.setServer`. Example:
```js
var request = remote.requestServerInfo();
request.setServer('wss://s1.ripple.com');
request.request(function(err, res) {
});
```
**[requestPeers([callback])](https://ripple.com/wiki/JSON_Messages#peers)**
**[requestConnect(ip, port, [callback])](https://ripple.com/wiki/JSON_Messages#connect)**
**[unl_list([callback])](https://ripple.com/wiki/JSON_Messages#unl_list)**
```js
var request = remote.request('un_list');
request.setServer('wss://s1.ripple.com');
request.request(function(err, res) {
});
```
**[unl_add(addr, comment, [callback])](https://ripple.com/wiki/JSON_Messages#unl_add)**
**[unl_delete(node, [callback])](https://ripple.com/wiki/JSON_Messages#unl_delete)**
##Ledger requests
**[requestLedger([opts], [callback])](https://ripple.com/wiki/JSON_Messages#ledger)**
**[requestLedgerHeader([callback])](https://wiki.ripple.com/JSON_Messages#ledger_data)**
**[requestLedgerCurrent([callback])](https://ripple.com/wiki/JSON_Messages#ledger_current)**
**[requestLedgerEntry(type, [callback])](https://ripple.com/wiki/JSON_Messages#ledger_entry)**
**[requestSubscribe([streams], [callback])](https://ripple.com/wiki/JSON_Messages#subscribe)**
Start receiving selected streams from the server.
**[requestUnsubscribe([streams], [callback])](https://ripple.com/wiki/JSON_Messages#unsubscribe)**
Stop receiving selected streams from the server.
##Account requests
**[requestAccountInfo(options, [callback])](https://ripple.com/wiki/JSON_Messages#account_info)**
Return information about the specified account.
```
var options = {
account: 'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B',
ledger: 'validated'
};
var request = remote.requestAccountInfo(options, function(err, info) {
/* process info */
});
// response
{
ledger_current_index: <number>,
account_data: {
Account: <string>,
Balance: <number>,
Flags: <number>,
LedgerEntryType: <string>,
OwnerCount: <number>,
PreviousTxnID: <string>,
PreviousTxnLgrSeq: <number>,
Sequence: <number> ,
index: <string>
}
}
```
**[requestAccountLines(options, [callback])](https://ripple.com/wiki/JSON_Messages#account_lines)**
**[requestAccountOffers(options, [callback])](https://ripple.com/wiki/JSON_Messages#account_offers)**
Return the specified account's outstanding offers.
Requests for both `account_lines` and `account_offers` support paging. The amount of results per response can be configured with the `limit`.
The responses can be paged through by using the `marker`.
```
// A valid `ledger_index` or `ledger_hash` is required to provide a reliable result.
// Results can change between ledger closes, so the provided ledger will be used as base.
var options = {
account: < rippleAccount >,
limit: < Number between 10 and 400 >,
ledger: < valid ledger_index or ledger_hash >
}
// The `marker` comes back in an account request if there are more results than are returned
// in the current response. The amount of results per response are determined by the `limit`.
if (marker) {
options.marker = < marker >;
}
var request = remote.requestAccountOffers(options);
```
**[requestAccountTransactions(options, [callback])](https://ripple.com/wiki/JSON_Messages#account_tx)**
Fetch a list of transactions that applied to this account.
Options:
+ `account`
+ `ledger_index_min`
+ `ledger_index_max`
+ `binary` *false*
+ `count` *false*
+ `descending` *false*
+ `offset` *0*
+ `limit`
+ `forward` *false*
+ `fwd_marker`
+ `rev_marker`
**[requestWalletAccounts(seed, [callback])](https://ripple.com/wiki/JSON_Messages#wallet_accounts)**
Return a list of accounts for a wallet. *Requires trusted remote*
**requestAccountBalance(account, [ledger], [callback])**
Get the balance for an account. Returns an [Amount](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/amount.js) object.
**requestAccountFlags(account, [ledger], [callback])**
Return the flags for an account.
**requestOwnerCount(account, [ledger], [callback])**
Return the owner count for an account.
**requestRippleBalance(account, issuer, currency, [ledger], [callback])**
Return a request to get a ripple balance
##Orderbook requests
**[requestBookOffers(options, [callback])](https://ripple.com/wiki/JSON_Messages#book_offers)**
Return the offers for an order book, also called a *snapshot*
```js
var options = {
gets: {
issuer: < issuer >,
currency: < currency >
},
pays: {
issuer: < issuer >,
currency: < currency >
},
limit: < limit >
};
var request = remote.requestBookOffers(options, function(err, offers) {
// handle offers
});
```
##Transaction requests
**[requestTransactionEntry(hash, [ledger_hash], [callback])](https://ripple.com/wiki/JSON_Messages#transaction_entry)**
Searches a particular ledger for a transaction hash. Default ledger is the open ledger.
**[requestTransaction(hash, [callback])](https://ripple.com/wiki/JSON_Messages#tx)**
Searches ledger history for validated transaction hashes.
**[requestSign(secret, tx_json, [callback])](https://ripple.com/wiki/JSON_Messages#sign)**
Sign a transaction. *Requires trusted remote*
**[requestSubmit([callback])](https://ripple.com/wiki/JSON_Messages#submit)**
Submit a transaction to the network. This command is used internally to submit transactions with a greater degree of reliability. See [Submitting a payment to the network](GUIDES.md#3-submitting-a-payment-to-the-network) for details.
**[pathFind(src_account, dst_account, dst_amount, src_currencies)](https://ripple.com/wiki/JSON_Messages#path_find)**
#Transaction constructors
Use `remote.createTransaction('TransactionType', [options])` to construct a transaction. To submit, use `transaction.submit([callback])`.
**Payment**
```js
var transaction = remote.createTransaction('Payment', {
account: MY_ADDRESS,
destination: DEST_ADDRESS,
amount: AMOUNT
});
```
**AccountSet**
```js
var transaction = remote.createTransaction('AccountSet', {
account: MY_ADDRESS,
set: 'RequireDest',
clear: 'RequireAuth'
});
```
**TrustSet**
```js
var transaction = remote.createTransaction('TrustSet', {
account: MY_ADDRESS,
limit: '1/USD/rrrrrrrrrrrrrrrrrrrrBZbvji'
});
```
**OfferCreate**
```js
var transaction = remote.createTransaction('OfferCreate', {
account: MY_ADDRESS,
taker_pays: '1',
taker_gets: '1/USD/rrrrrrrrrrrrrrrrrrrrBZbvji'
});
```
##Transaction events
[Transaction](https://github.com/ripple/ripple-lib/blob/develop/src/js/ripple/transaction.js) objects are EventEmitters. They may emit the following events.
+ `final` Transaction has erred or succeeded. This event indicates that the transaction has finished processing.
+ `error` Transaction has erred. This event is a final state.
+ `success` Transaction succeeded. This event is a final state.
+ `presubmit` Immediately before transaction is submitted
+ `postsubmit` Immediately after transaction is submitted
+ `submitted` Transaction has been submitted to the network. The submission may result in a remote error or success.
+ `resubmitted` Transaction is beginning resubmission.
+ `proposed` Transaction has been submitted *successfully* to the network. The transaction at this point is awaiting validation in a ledger.
+ `timeout` Transaction submission timed out. The transaction will be resubmitted.
+ `fee_adjusted` Transaction fee has been adjusted during its pending state. The transaction fee will only be adjusted if the remote is configured for local fees, which it is by default.
+ `abort` Transaction has been aborted. Transactions are only aborted by manual calls to `#abort`.
+ `missing` Four ledgers have closed without detecting validated transaction
+ `lost` Eight ledgers have closed without detecting validated transaction. Consider the transaction lost and err/finalize.
##Complete payment example
```js
remote.setSecret(MY_ADDRESS, MY_SECRET);
var transaction = remote.createTransaction('Payment', {
account: MY_ADDRESS,
destination: DEST_ADDRESS,
amount: AMOUNT
});
transaction.on('resubmitted', function() {
// initial submission failed, resubmitting
});
transaction.submit(function(err, res) {
// submission has finalized with either an error or success.
// the transaction will not be retried after this point
});
```
#Amount objects
Coming Soon
#Subscriptions
##Orderbook subscription
Subscribes to an orderbook (including autobridged books). Send the orderbook on subscribe then notifies updates.
Available events: ['transaction', 'model', 'trade', 'offer_added', 'offer_removed', 'offer_changed', 'offer_funds_changed']
```js
parameters = {
currency_pays: <string>,
issuer_pays: <string>,
currency_gets: <string>,
issuer_gets: <string>
}
```
Basic subscription:
```js
var Orderbook = Remote.book(parameters);
Orderbook.on('model', handler);
```

168
docs/VAULTCLIENT.md
View File

@@ -1,168 +0,0 @@
ripple-vault-client
===================
A javascript / http client to interact with Ripple Vault servers.
The purpose of this tool is to enable applications in any javascript
environment to login with the ripple vault and access the decrypted
data stored using credentials originally obtained at ripple.com
## Vault Client Usage
vaultClient = new ripple.VaultClient(domain);
vaultClient.getAuthInfo(username, callback);
vaultClient.getRippleName(address, url, callback);
vaultClient.exists(username, callback);
vaultClient.login(username, password, callback);
vaultClient.relogin(id, cryptKey, callback);
vaultClient.unlock(username, password, encryptSecret, callback);
vaultClient.loginAndUnlock(username, password, callback);
vaultClient.register(options, callback);
vaultClient.deleteBlob(options, callback);
vaultClient.recoverBlob(options, callback);
vaultClient.rename(options, callback);
vaultClient.changePassword(options, callback);
vaultClient.verify(username, token, callback);
vaultClient.resendEmail(options, callback);
vaultClient.updateProfile(options, fn);
# Blob Methods
blob.encrypt();
blob.decrypt(encryptedBlob);
blob.encryptSecret(encryptionKey);
blob.decryptSecret(encryptionKey, secret);
blob.set(pointer, value, callback);
blob.unset(pointer, callback);
blob.extend(pointer, value, callback);
blob.unshift(pointer, value, callback);
blob.filter(pointer, field, value, subcommands, callback);
## Identity Vault
The identity vault stores identity information inside the encrypted
blob vault. The identity fields can be additionally encrypted with the
unlock key, that encrypts the secret, for added security. Methods are
accessed from the 'identity' property of the blob object.
# Identity fields
+ name
+ entityType (individual, corporation, organization)
+ email
+ phone
+ address
+ contact
+ line1
+ line2
+ city
+ postalCode
+ region - state/province/region
+ country
+ nationalID
+ number
+ type (ssn, taxID, passport, driversLicense, other)
+ country - issuing country
+ birthday
+ birthplace
# Identity Methods
blob.identity.set(pointer, key, value, callback);
blob.identity.unset(pointer, key, callback);
blob.identity.get(pointer, key);
blob.identity.getAll(key);
blob.identity.getFullAddress(key); //get text string of full address
## Spec Tests
Run `npm test` to test the high-level behavior specs
Ripple Txt
✓ should get the content of a ripple.txt file from a given domain
✓ should get currencies from a ripple.txt file for a given domain
✓ should get the domain from a given url
AuthInfo
✓ should get auth info
VaultClient
#initialization
✓ should be initialized with a domain
✓ should default to ripple.com without a domain
#exists
✓ should determine if a username exists on the domain
#login
✓ with username and password should retrive the blob, crypt key, and id
#relogin
✓ should retrieve the decrypted blob with blob vault url, id, and crypt key
#unlock
✓ should access the wallet secret using encryption secret, username and password
#loginAndUnlock
✓ should get the decrypted blob and decrypted secret given name and password
#register
✓ should create a new blob
#deleteBlob
✓ should remove an existing blob
#updateProfile
✓ should update profile parameters associated with a blob
Blob
✓ #set
✓ #extend
✓ #unset
✓ #unshift
✓ #filter
✓ #consolidate
#rename
✓ should change the username of a blob
#changePassword
✓ should change the password and keys of a blob
#recoverBlob
✓ should recover the blob given a username and secret
#verifyEmail
✓ should verify an email given a username and token
#resendVerifcationEmail
✓ should resend a verification given options
identity
✓ #identity_set
✓ #identity_get
✓ #identity_getAll
✓ #identity_getFullAddress
✓ #identity_unset