Skip to content

Commit

Permalink
docs: cleanup readme (#1485)
Browse files Browse the repository at this point in the history
* docs: cleanup readme

* docs: cleanup docs

* docs: remove outdated docs
  • Loading branch information
vacekj authored Jul 17, 2024
1 parent ea6c2e1 commit c3184f9
Show file tree
Hide file tree
Showing 8 changed files with 1 addition and 279 deletions.
26 changes: 1 addition & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,34 +75,10 @@ pnpm dev
```

You now have a local copy of Minifront available at
[`https://localhost:5173`](https://localhost:5173) and an unbundled Prax is
available at [`apps/extension/dist`](apps/extension/dist), ready to be loaded
into your browser.
[`https://localhost:5173`](https://localhost:5173).

Minifront will hot-reload.

If you're working on Prax, Chrome will show extension page changes after a
manual refresh, but cannot reload the extension worker scripts or content
scripts. For worker script changes, you must manually reload the extension. For
content script changes, you must also manually reload pages hosting the injected
scripts.

#### Loading your unbundled build of Prax into Chrome

After building Prax, you can load it into Chrome.

It's recommended to use a dedicated browser profile for development, not your
personal profile.

1. Go to the Extensions page [`chrome://extensions`](chrome://extensions)
2. Enable _Developer Mode_ by clicking the toggle switch at the top right
3. Click the button _Load unpacked extension_ at the top and locate your cloned
repository. Select the extension's build output directory
[`apps/extension/dist`](../apps/extension/dist).
4. Activate the extension to enter onboarding.
- You may set a blank password.
- You can pin the Prax extension button to your toolbar for quick access.

## Security

If you believe you've found a security-related issue with Penumbra,
Expand Down
24 changes: 0 additions & 24 deletions docs/custody.md

This file was deleted.

14 changes: 0 additions & 14 deletions docs/deployment.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,5 @@
# Deployment Workflows

### Prax Chrome Extension

Create a [github issue deployment issue](https://github.com/penumbra-zone/web/issues/new?template=deployment.md&title=Publish+vX.X.X+extension+%2B+web+app) to track deployment progress and steps.

Upon a new [git tag](https://github.com/penumbra-zone/web/releases/tag/v4.2.0) being pushed to the repo,
a [workflow](../.github/workflows/extension-publish.yml) is kicked off. It then requests permission to
continue from [github group](https://github.com/orgs/penumbra-zone/teams/penumbra-labs) and, after approval,
bundles the extension into a .zip which gets put in the Chrome Webstore review queue. It typically takes
1-3 days to go live. The publication status can be monitored in the [Chrome Developer Dashboard](https://chrome.google.com/webstore/devconsole/aabc0949-93db-4e77-ad9f-e6ca1d132501?hl=en).

### Web app

Manually run [Deploy Firebase Dapp](https://github.com/penumbra-zone/web/actions/workflows/deploy-firebase-dapp.yml) github action on main branch.

### NPM Packages

The packages in this repo are published using [changesets](https://github.com/changesets/changesets).
Expand Down
97 changes: 0 additions & 97 deletions docs/extension-services.md
Original file line number Diff line number Diff line change
@@ -1,100 +1,3 @@
# Extension Services

Prax uses a custom transport for `@connectrpc/connect` to provide
Protobuf-specified services via a DOM channel `MessagePort` and the Chrome
extension runtime.

Interestingly, this transport should be generally applicable to any
Protobuf-specified interface, including all auto-generated clients and server
stubs from the buf registry.

If you are interested in using the transport for
your own project, the generic packages are available in
`@penumbra-zone/transport-dom` and `@penumbra-zone/transport-chrome`.

You may use locally generated service types, or simply install the [appropriate
packages from the buf
registry](https://buf.build/penumbra-zone/penumbra/sdks/main). If you are using
npm, buf's [npm-specific guide](https://buf.build/docs/bsr/generated-sdks/npm)
is recommended reading.

## Clients

Each channel transport can be used as a page-level singleton servicing multiple
clients. Developers using React queriers may be interested in
`@connectrpc/connect-query`.

Creation is fully synchronous from the constructor's perspective, and the client
is immediately useable, but requests are delayed until init actually completes.

### Connection to Prax

For developing a dapp that connects to Prax, you may use the convenience functions in `@penumbra-zone/client`.

```ts
import { createPraxClient } from '@penumbra-zone/client';
import { ViewService } from '@penumbra-zone/protobuf';

const viewClient = createPraxClient(ViewService);
```

An incredibly simple use might be something like this.

```ts
import { bech32mAddress } from '@penumbra-zone/bech32m/penumbra';

const { address } = await viewClient.addressByIndex({});
console.log(bech32mAddress(address));
```

### More control

Other providers may be available, and you can configure the transport however
you'd like. Use of the client is identical.

```ts
import { getAnyPenumbraPort } from '@penumbra-zone/client';
import { ViewService } from '@penumbra-zone/protobuf';
import { bech32mAddress } from '@penumbra-zone/bech32m/penumbra';

const channelTransport = createChannelTransport({
getPort: getAnyPenumbraPort,
jsonOptions: { typeRegistry: createRegistry(ViewService) },
});

const viewClient = createPromiseClient(ViewService, channelTransport);
const { address } = await viewClient.addressByIndex({});
console.log(bech32mAddress(address));
```

### The actual interface

These are just convenience methods to this interface. A global record, on which
arbitrary strings identify providers, with a simple interface to connect or
request permission to connect.

If you're developing a wallet, injection of a record here will allow you to
expose your wallet to potentially interested web apps.

<!-- keep in sync with @penumbra-zone/client/global.ts` -->

```ts
export const PenumbraSymbol = Symbol.for('penumbra');

export interface PenumbraProvider {
readonly connect: () => Promise<MessagePort>;
readonly request: () => Promise<boolean | undefined>;
readonly isConnected: () => boolean | undefined;
readonly manifest: string;
}

declare global {
interface Window {
readonly [PenumbraSymbol]?: undefined | Readonly<Record<string, PenumbraProvider>>;
}
}
```

## Service Implementation

Services in this repository should eventually be re-useable, but you can also
Expand Down
54 changes: 0 additions & 54 deletions docs/publishing.md

This file was deleted.

50 changes: 0 additions & 50 deletions docs/state-management.md

This file was deleted.

1 change: 0 additions & 1 deletion docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ much as we can. If we do, our app will be far more resilient to changes.
Different kinds of testing examples:

- Unit tests: [packages/crypto/src/encryption.test.ts](../packages/crypto/src/encryption.test.ts)
- Zustand store tests: [apps/extension/src/state/password.test.ts](../apps/extension/src/state/password.test.ts)
- Zod tests to validate types: [packages/wasm/src/client.test.ts](../packages/wasm/src/keys.test.ts)

### Vitest
Expand Down
14 changes: 0 additions & 14 deletions docs/web-workers.md

This file was deleted.

0 comments on commit c3184f9

Please sign in to comment.