@satellite-im/iridium NPM

Iridium Protocol

Iridium is a loosely defined protocol for peer-to-peer communication and storage for user application data (profile, friends, messages, files, etc...) leveraging IPFS and dag-jose.

Developing with Iridium

Node version

If you are linking Iridium locally, Node 18 is currently required for debugging purposes. verify that you are running Node 18 before you attempt the next step.

node -v
# expected output: v18.*.*

Install Dependencies

# install npm dependencies:
pnpm i

Run the Sync Node

pnpm sync-node
# or, run it via docker
docker compose up -d

Building & Watching for Changes

pnpm build
# or, to watch for changes:
pnpm watch

Linking the module

Now you can link Iridium in a local project:

# from the iridium directory:
pnpm link . --global
# OR
yarn link

# from the other project directory:
pnpm link @satellite-im/iridium --global
# OR
yarn link @satellite-im/iridium

Creating an Iridium Instance

const client = await Iridium.fromSeedString('user a seed', {
  config: {
    // peerIds to automatically establish a connection with
    followedPeers: ['12D3KooWJANMEJ97LJzLFH6N5Wgz63v8Qrv5rvyTm1iHu7asPasp'],
    // ipfs node config
    ipfs: {
      config: {
        Addresses: {
          // addresses to LISTEN ON
          Swarm: ['/ip4/127.0.0.1/tcp/9000', '/ip4/127.0.0.1/tcp/9001/ws'],
        },
        Boostrap: [
          // addresses to CONNECT TO
        ],
      },
      libp2p: {
        // p2p configuration
      },
    },
  },
})

Direct Peer Communication

await iridium.send(
  someOtherDID,
  {
    type: 'friend:request',
    displayName,
    profilePicture,
  },
  { encrypt: true },
)

iridium.on('message', ({ from, payload }) => {
  const { type } = payload
  if (type === 'friend:request') {
    /* ... */
  } else if (type === 'signed:message') {
    /* ... */
  } else if (type === 'secret:message') {
    /* ... */
  }
})

Pubsub

// user-b
iridium.followPeer(userAPeerId)
iridium.on('peer:channel_name', ({ from, payload }) => {
  if (from === userAPeerId) {
    // do a thing
  }
})

// user-a
await iridium.broadcast('channel_name', payload)

Managing User Documents

// fetch the root level IPNS document
const userData = await iridium.get('/')
await iridium.set('/profile', {
  name: 'foo bar',
  friends: [
    {
      id: 1,
      name: 'bar baz',
    },
  ],
})
const friend = await iridium.get('/profile/friends/0')
await iridium.set('/profile/friends/0', {
  ...friend,
  profilePicture,
})

Managing Other Documents

// config can include `encrypt`, `sign`, `dag` options
const cid = await iridium.store(document, arrayOfTargetDIDs, config)
const doc = await iridium.load(cid) // throws if signature invalid

Run with docker-compose

Setup env file

Server names in nginx configuration are composed in the following way:

Sync Agent: server_name ${SYNC_PREFIX}.${HOSTNAME}

Libp2p relay server: server_name ${RELAY_PREFIX}.${HOSTNAME}

To customize the endpoint the corresponding environment variables must be set in the env file

#### NGINX ####
SYNC_PREFIX="sync"
RELAY_PREFIX="relay"
HOSTNAME="satellite.im"

Certbot configuration can be customized by environment variables

#### CERTBOT ####
CERTBOT_EMAIL=support@satellite.im # required

# Optional (Defaults)
DHPARAM_SIZE=2048
ELLIPTIC_CURVE=secp256r1
RENEWAL_INTERVAL=8d
RSA_KEY_SIZE=2048
STAGING=0
USE_ECDSA=1

# Advanced (Defaults)
CERTBOT_AUTHENTICATOR=webroot
CERTBOT_DNS_PROPAGATION_SECONDS=""
DEBUG=0
USE_LOCAL_CA=0 # For local development