@@ -0,0 +1,51 @@
1+:- :~ title/'Using a Star'
7+A _ship_ is an instance of the Arvo operating system that is used as a personal server on the Arvo network. Stars are a type of ship that act as infrastructure for the Arvo network. In the Arvo ship-hierarchy, stars are below galaxies and above planets.
9+Parallel to the Arvo network is Azimuth, the Urbit identity system that uses the Ethereum blockchain. All ships must boot with a corresponding _point_ -- an Azimuth identity -- to use the Arvo network.
11+Important star operations happen on both the Arvo side and the Azimuth side. On the Arvo side, these operations come in the form of Dojo commands. On the Azimuth side, operations happen by making changes to smart-contracts on the blockchain via a point.
15+Stars are above planets in the network hierarchy in the sense that each star sponsors some number of planets: stars discover peers for planets, route packets for planets, provide DNS routing for planets, and push software updates to planets. A star that fulfills this is called the *sponsor* of planets that receive such services from the star; those planets, in turn, are called *dependents* of that star.
17+Stars are also the "parents" planets. A new planet comes into existence only when spawned by a parent star. A parent planet is the sponsor of its children planets by default. This can change if a planet chooses to find a new sponsor (see the "Escaping a Sponsor" section below).
19+Planets must have a sponsor star to use most features of the Arvo network. A planet cannot boot without a sponsor, and cannot make new connections to peers as long as it is not connected to a sponsor. Sponsorless planets will still be able to message discovered peers until such any such peers change their IP addresses.
21+## Responsibility of a Star
23+Like with real-life infrastructure, the operation of Arvo infrastructure comes with unique responsibilities. For reasons stated above, stars should be always be online on a reliable cloud service, such as Amazon Web Services or Google Cloud Platform. These systems have layers of redundancies that make them much more resilient than local machines, so stars hosted on the cloud are unlikely to leave their dependents in the dark.
27+Below are some handy operations for the use and maintenance of your star.
31+You star is not aware of its own IP address by default. This means its dependent planets won't get DNS routing.
33+To provide DNS routing to your star's dependents, you need to set your star's IP address.
35++ Wait for the initial post-boot sync to succeed.
36++ Enter `:dns|ip` into the Dojo.
37++ The dojo will prompt you to enter something. Enter your IP address here.
39+### Maintaining Connectivity
41+Occasionally, your star might lose network connectivity due to a known timer issue. When this happens, enter the `|bonk` command in the Dojo to reset the timer and restore connectivity.
43+### Escaping a Sponsor
45+Planets are, of course, able to change sponsors. To do this, they must request that a different star takes them on a dependent and that planet must accept the request. Planets cannot emancipate themselves from a sponsor without having a new sponsor lined up.
47+All of these actions happen on Azimuth. There will be Bridge functionality to handle these actions in the future, but for now users will need to interact directly with the contracts with MetaMask, through services such as [Etherscan.io](https://etherscan.io/address/ecliptic.eth#writeContract). A sketch of the process is listed below; for now, only the Ethereum-savvy should act on these steps.
49++ The planet calls the `escape` function in the Ecliptic contract and writes the resulting data to the blockchain.
50++ If the chosen star wants to become the planet's sponsor, it calls the `adopt` function in the Ecliptic contract.
51++ The Arvo network notices the change, and the operation is complete.