Urbit Constitution client module

Install

npm install urbit-constitution-client --save

Test

npm 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.

Validation and Formatting Functions

toAddress(shipName)

Converts an Urbit ship name to its address

toShipName(shipAddress)

Converts an Urbit address to its ship name

valGalaxy(galaxyAddress)

Validates an Urbit galaxy address

valStar(starAddress)

Validates an Urbit star address

valShip(shipAddress)

Validates an Urbit ship address

valAddress(ethAddress)

Validates an Ether address

formatShipName(shipName)

Adds a tilde to a valid Urbit ship name

getSpawnCandidate(shipAddress)

Returns the address of a random spawn candidate from the Urbit ship address. This call does NOT guarantee availability of the returned address.

Read Functions

Read Urbit ship data stored on the blockchain

buildOwnedShips(ethAddress, callback)

Returns an object loaded with the ships owned by ethAddress

getConstitutionOwner(callback)

Returns the Ether address of the owner of the Urbit constitution

readShipData(shipAddress, callback)

Returns hasBeenBooted bool for ship with shipAddress

readHasOwner(shipAddress, callback)

Returns a bool for whether ship with shipAddress has an owner

readIsOwner(shipAddress, ethAddress, callback)

Returns true if ethAddress owns the ship at shipAddress

readPoolAssets(poolAddress, callback)

Returns the total Spark assets of the pool at poolAddress

readBalance(poolAddress, callback)

Returns the balance of Spark assets in the pool at poolAddress held by the given wallet

readParent(shipAddress, callback)

Returns the parent ship address of shipAddress

readOwnedShips(ethAddress, callback)

Returns the list of ships owned by ethAddress

readIsRequestingEscapeTo(shipAddress, sponsorAddress, callback)

Returns a bool for whether shipAddress is currently requesting an escape to sponsorAddress

readKeys(shipAddress, callback)

Returns the keys for ship at shipAddress

readIsSpawnProxy(shipAddress, ethAddress, callback)

Returns a bool for whether ethAddress is the spawn proxy of shipAddress

Transaction Functions

The callback in each of these functions returns an object in this format:

{ 
  error: false,
  rawTx: 
    '{
  	  "nonce":"0x14",
  	  "gasPrice":"0x04e3b29200",
  	  "gasLimit":"0x0446c6",
  	  "to":"0x098b6cb45da68c31c751d9df211cbe3056c356d1",
  	  "value":"0x00",
  	  "data":"0xa0d3253f000000000000000000000000000000000000000000000000000000002f2701000000000000000000000000006deffb0cafdb11d175f123f6891aa64f01c24f7d",
  	  "chainId":1
    }',
  signedTx: '0xf8aa148504e3b29200830446c694098b6cb45da68c31c751d9df211cbe3056c356d180b844a0d3253f000000000000000000000000000000000000000000000000000000002f2701000000000000000000000000006deffb0cafdb11d175f123f6891aa64f01c24f7d25a0f216335c74c4e7151feaa1afb83bf5d08cfc72eab336268e5edd4ffae6ca3f55a068ffbb95cd3eb20b2aaf83960df96e1ff6ff3ddce2d68ca4fd762de8fcd350cd',
  showRaw: true 
}

doCreateGalaxy(galaxy, callback)

Create galaxy

doDeposit(star, poolAddress, callback)

Deposit star into the pool at poolAddress

doWithdraw(star, poolAddress, callback)

Withdraw star from the pool at poolAddress

doSpawn(shipAddress, callback)

Spawn ship shipAddress

doSetSpawnProxy(shipAddress, ethAddress, callback)

Set ethAddress as the spawn proxy of shipAddress

doConfigureKeys(shipAddress, encryptionKey, authenticationKey, discontinuous, callback)

Set encryptionKey and authenticationKey as the keys for shipAddress. bool discontinuous optionally increments the continuity number of shipAddress

doTransferShip(shipAddress, ethAddress, reset, callback)

Transfer shipAddress to ethAddress. bool reset optionally clears the keys and breaks continuity

doSetTransferProxy(shipAddress, ethAddress, callback)

Set ethAddress as the transfer proxy for shipAddress

doEscape(shipAddress, sponsorAddress, callback)

Escape shipAddress to sponsorAddress

doAdopt(sponsorAddress, escapeeAddress, callback)

sponsorAddress adopts escapeeAddress

doReject(sponsorAddress, escapeeAddress, callback)

sponsorAddress rejects escapeeAddress

doApprove(ethAddress, shipAddress, callback)

Approve ethAddress to transfer shipAddress

doSafeTransferFrom(fromEthAddress, toEthAddress, shipAddress, callback)

Conduct a safe transfer of shipAddress from fromEthAddress to toEthAddress

doCastConstitutionVote(galaxy, prop, vote, callback)

Cast vote from galaxy on constitution proposal at prop

doCastDocumentVote(galaxy, prop, vote, callback)

Cast vote from galaxy on document proposal at prop

Send signed transactions

sendTx(signedTx, callback)

Submit signedTx to the blockchain. The object returned in the callback is in this format:

{ 
  error: false,
  data: 
    {
      resp: '0x5b32667f0ce0032007dba91c1011942a3140f826c69a6c689632caa91321c7b0',
   	  tx: 
        { 
      	  gasLimit: '',
          data: '',
          to: '',
          unit: 'ether',
          value: 0,
          nonce: null,
          gasPrice: null 
    	} 
    } 
}

Command Line Example

Get a random spawn candidate for a ship you own and then spawn it

1. Call getSpawnCandidate passing in the Urbit address of a ship you own

node -pe 'require("./index").getSpawnCandidate(256)'

Note that because this function doesn't use a callback this command uses the -pe flag in order to print the returned value. Most of the functions have callbacks, so their commands use the -e flag and console.log as the final parameter

Returned value

791085312

This function is a random number generator, so returned values will vary

2. Call doSpawn with the returned spawn candidate address

node -e 'require("./index").doSpawn(791085312,console.log)'

Returned object

{ 
  error: false,
  rawTx: 
    '{
  	  "nonce":"0x14",
  	  "gasPrice":"0x04e3b29200",
  	  "gasLimit":"0x0446c6",
  	  "to":"0x098b6cb45da68c31c751d9df211cbe3056c356d1",
  	  "value":"0x00",
  	  "data":"0xa0d3253f000000000000000000000000000000000000000000000000000000002f2701000000000000000000000000006deffb0cafdb11d175f123f6891aa64f01c24f7d",
  	  "chainId":1
    }',
  signedTx: '0xf8aa148504e3b29200830446c694098b6cb45da68c31c751d9df211cbe3056c356d180b844a0d3253f000000000000000000000000000000000000000000000000000000002f2701000000000000000000000000006deffb0cafdb11d175f123f6891aa64f01c24f7d25a0f216335c74c4e7151feaa1afb83bf5d08cfc72eab336268e5edd4ffae6ca3f55a068ffbb95cd3eb20b2aaf83960df96e1ff6ff3ddce2d68ca4fd762de8fcd350cd',
  showRaw: true 
}

3. Call sendTx with the signedTx value from the returned object

node -e 'require("./index").sendTx("0xf8aa148504e3b29200830446c694098b6cb45da68c31c751d9df211cbe3056c356d180b844a0d3253f000000000000000000000000000000000000000000000000000000002f2701000000000000000000000000006deffb0cafdb11d175f123f6891aa64f01c24f7d25a0f216335c74c4e7151feaa1afb83bf5d08cfc72eab336268e5edd4ffae6ca3f55a068ffbb95cd3eb20b2aaf83960df96e1ff6ff3ddce2d68ca4fd762de8fcd350cd",console.log)'

Returned object

{ 
  error: false,
  data: 
    {
      resp: '0x5b32667f0ce0032007dba91c1011942a3140f826c69a6c689632caa91321c7b0',
   	  tx: 
        { 
      	  gasLimit: '',
          data: '',
          to: '',
          unit: 'ether',
          value: 0,
          nonce: null,
          gasPrice: null 
    	} 
    } 
}

4. Call buildOwnedShips to see your newly spawned ship

node -e 'require("./index").buildOwnedShips("0x6deffb0cafdb11d175f123f6891aa64f01c24f7d",console.log)'

Returned object

{
  '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