constitution-js v0.4.1
Urbit Constitution-JS
Install
npm install constitution-js --save
Development
Testnet
In order to test the functionality of the Wallet, you'll need a testnet running the
Urbit constitution.
1. Clone the constitution
2. cd
into the repo and npm install
3. npm install -g ganache-cli
3. Run a local ganache
node, boot using the following command to ensure a matching seed:
ganache-cli -m "benefit crew supreme gesture quantum web media hazard theory mercy wing kitten"
4. Run truffle deploy
from the constitution's directory to deploy to your local node.
Useful addresses
Constitution owner (is allowed to create galaxies): 0x6deffb0cafdb11d175f123f6891aa64f01c24f7d
Test pool: 0x0724ee9912836c2563eee031a739dda6dd775333
Test
npm test
Run ganache-cli -m "benefit crew supreme gesture quantum web media hazard theory mercy wing kitten"
and truffle deploy
before starting the test.
Important things to know
There are three categories of Urbit ships: galaxies, stars, and planets. Galaxies spawn stars. Stars spawn planets.
Each Urbit ship has a unique integer address. Galaxy addresses are numbered 0 - 255 (2^8). Star addresses are numbered 256 - 65,535 (2^16). Planet addresses are numbered 65,536 - 4,294,967,295 (2^32).
Each Urbit ship also has a unique human-readable name that's determined from its address.
Functions
Config
setServerUrl(serverURL)
Set the URL serverURL
for web3
setPrivateKey(hd, path, index, callback)
Set the HDKey hd
, path path
, and index index
of the address to use. Callback returns the address at index
.
setDefaultAccountWithPathAndIndex(path, index, callback)
Set the path path
and index index
of the address to use. Call this after calling setPrivateKey()
if you want to switch to a different address from the one originally specified. Callback returns the address at index
.
setPoolAddress(poolAddress)
Set the ETH address of the pool poolAddress
to use. (Optional, defaults to standard pool)
Validation and Formatting
valGalaxy(galaxyAddress)
Returns a bool validating Urbit galaxy address galaxyAddress
valStar(starAddress)
Returns a bool validating Urbit star address starAddress
valShip(shipAddress)
Returns a bool validating Urbit ship address shipAddress
valAddress(ethAddress)
Returns a bool validating Ether address ethAddress
.
formatShipName(shipName)
Returns a string with a tilde added to a valid Urbit ship name shipName
toAddress(shipName)
Return the corresponding Urbit ship address of ship with name shipName
toShipName(shipAddress)
Returns the coorresponding Urbit ship name of ship with address shipAddress
getSpawnCandidate(shipAddress)
Returns the Urbit ship address of a random spawn candidate from ship with address shipAddress
. This call does NOT guarantee availability of the returned address.
Read
Read Urbit ship data stored on the blockchain
readShipData(shipAddress, callback)
Returns hasBeenBooted
bool for ship shipAddress
readOwnedShips(ethAddress, callback)
Returns an object loaded with the ships owned by the account ethAddress
readOwnedShipsStatus(ethAddress, callback)
Returns an object loaded with the ships owned by ethAddress
including their name
and hasBeenBooted
status
readTransferringFor(ethAddress, callback)
Returns an object loaded with the pending transfer ships by the account ethAddress
readHasOwner(shipAddress, callback)
Returns a bool for whether ship shipAddress
has an owner
readIsOwner(shipAddress, ethAddress, callback)
Returns true
if ethAddress
owns the ship shipAddress
readSponsor(shipAddress, callback)
Returns the address of the sponsor of ship shipAddress
readPoolAssets(poolAddress, callback)
Returns an array of Urbit star names held by the pool poolAddress
readBalance(poolAddress, callback)
Returns the balance of Spark assets in the pool poolAddress
held by the given wallet
readIsRequestingEscapeTo(shipAddress, sponsorAddress, callback)
Returns a bool for whether ship shipAddress
is currently requesting an escape to ship sponsorAddress
readKeys(shipAddress, callback)
Returns the keys for ship shipAddress
readIsSpawnProxy(shipAddress, ethAddress, callback)
Returns a bool for whether the account ethAddress
is the spawn proxy of the shipshipAddress
Transactions
The callback in each of these functions returns an object in this format:
{
error: false,
signedTx: '0xf8b0138504a817c80083038af494098b6cb45da68c31c751d9df211cbe3056c356d180b84426295b5200000000000000000000000000000000000000000000000000000000000000d70000000000000000000000006deffb0cafdb11d175f123f6891aa64f01c24f7d8602c9e6a44eb5a0a6a65a5455e0e5377685be404840eaf917bb5aaeeaf95603e48a7b4498c0d5b0a00ee33788ab4d08e87759f34ea7fb72c2031e9033a63bfcb6ed77a92e1d298c5e',
rawTx:
{
from: '0x6deffb0cafdb11d175f123f6891aa64f01c24f7d',
to: '0x098b6cb45da68c31c751d9df211cbe3056c356d1',
value: '0x0',
data: '0x26295b5200000000000000000000000000000000000000000000000000000000000000d70000000000000000000000006deffb0cafdb11d175f123f6891aa64f01c24f7d',
gas: '0x38af4',
chainId: '0x164f3522749',
gasPrice: '0x4a817c800',
nonce: '0x13'
}
}
doCreateGalaxy(galaxy, ethAddress, callback)
Create galaxy galaxy
and give it to address ethAddress
doDeposit(star, poolAddress, callback)
Deposit ship star
into the pool at poolAddress
doWithdraw(star, poolAddress, callback)
Withdraw star
from the pool at poolAddress
doSpawn(shipAddress, ethAddress, callback)
Spawn ship shipAddress
and give it to address ethAddress
doSetSpawnProxy(shipAddress, ethAddress, callback)
Set ethAddress
as the spawn proxy of shipAddress
doConfigureKeys(shipAddress, encryptionKey, authenticationKey, cryptoSuiteVersion, discontinuous, callback)
Set encryptionKey
and authenticationKey
as the keys for ship shipAddress
with corresponding cryptoSuiteVersion
. bool discontinuous
optionally increments the continuity number of ship shipAddress
doTransferShip(shipAddress, ethAddress, reset, callback)
Transfer ship shipAddress
to address ethAddress
. bool reset
optionally clears the keys and breaks continuity
doSetTransferProxy(shipAddress, ethAddress, callback)
Set address ethAddress
as the transfer proxy for ship shipAddress
doEscape(shipAddress, sponsorAddress, callback)
Escape ship shipAddress
to ship sponsorAddress
doAdopt(sponsorAddress, escapeeAddress, callback)
Ship sponsorAddress
adopts ship escapeeAddress
doReject(sponsorAddress, escapeeAddress, callback)
Ship sponsorAddress
rejects ship escapeeAddress
doApprove(ethAddress, shipAddress, callback)
Approve address ethAddress
to transfer ship shipAddress
doSafeTransferFrom(fromEthAddress, toEthAddress, shipAddress, callback)
Conduct a safe transfer of ship shipAddress
from address fromEthAddress
to address toEthAddress
doCastConstitutionVote(galaxy, prop, vote, callback)
Cast bool vote vote
from galaxy galaxy
on constitution proposal at address prop
doCastDocumentVote(galaxy, prop, vote, callback)
Cast bool vote
from galaxy galaxy
on document proposal at address prop
Send
sendTransaction(signedTx, callback)
Submit signedTx
to the blockchain. The object returned in the callback is in this format:
{
error: false,
txHash: '0xb6b61dc7e59a39dc141e8971e29f86175ef9e9ba0fc4ea2948351c4aa009a8e1'
}
Examples
1. Call setServerUrl
with the URL of your node. Then call setPrivateKey
with the HDKey and path of your account and the index of the address you want to use.
var bip39 = require('bip39');
var hdkey = require('hdkey');
var constitution = require('constitution-js');
constitution.setServerUrl('http://localhost:8545');
var mnemonic = 'benefit crew supreme gesture quantum web media hazard theory mercy wing kitten';
var masterKey = hdkey.fromMasterSeed(bip39.mnemonicToSeed(mnemonic));
var path = "m/44'/60'/0'/0";
var idx = 0;
constitution.setPrivateKey(masterKey, path, idx, function(res) {
if (!res.error) {
console.log(res);
}
});
Logged object
{
error: false,
data: 0x6DEfFb0caFDB11D175F123F6891AA64F01c24F7d
}
2. Call getSpawnCandidate
passing in the Urbit address of a ship you own
var spawnCandidate = constitution.getSpawnCandidate(256)
console.log(spawnCandidate);
Logged value
791085312
This function is a random number generator, so returned values will vary
3. Call readSponsor
constitution.readSponsor(256, function(res) {
if (!res.error) {
console.log(res);
}
});
Logged object
{
error: false,
data: 0
}
4. Call readOwnedShipsStatus
constitution.readOwnedShipsStatus('0x6deffb0cafdb11d175f123f6891aa64f01c24f7d', function(res) {
if (!res.error) {
console.log(res);
}
});
Logged object
{
error: false,
data:
{
'0': { name: '~zod', address: 0, hasBeenBooted: true },
'1': { name: '~nec', address: 1, hasBeenBooted: false },
'22': { name: '~lup', address: 22, hasBeenBooted: false },
'256': { name: '~marzod', address: 256, hasBeenBooted: true },
'512': { name: '~binzod', address: 512, hasBeenBooted: false },
'65792': { name: '~wicdev-wisryt', address: 65792, hasBeenBooted: false },
'131328': { name: '~panret-tocsel', address: 131328, hasBeenBooted: false },
'791085312': { name: '~fadnyd-worsef', address: 791085312, hasBeenBooted: false }
}
}
Find out more: https://urbit.org