Skip to content

Commit

Permalink
feat: improve doc and add links to all READMEs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@gdethier
gdethier committed Apr 23, 2024
1 parent afc485f commit ee6d101
Show file tree
Hide file tree
Showing 17 changed files with 106 additions and 361 deletions.
2 changes: 1 addition & 1 deletion packages/client-browser/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ Use your favorite package manager (e.g. yarn) and install package `@logion/clien

## Usage

See [core client](../client/README.md).
See [documentation](https://logion-network.github.io/logion-api/).
30 changes: 1 addition & 29 deletions packages/client-expo/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,32 +16,4 @@ global.Buffer = Buffer;

## Usage

Instantiate the Logion client using `newLogionClient` function. For example, to connect to our test environment use:

```typescript
import { Environment } from "@logion/client";
import { newLogionClient } from '@logion/client-expo';

const client = await newLogionClient(Environment.TEST);
```

See [here](../client/README.md) for instructions about how to use the client.

Each time you need to pass a file to the client (e.g. when creating a collection item or a tokens record),
pass an instance of `ExpoFile`. The constructor expects 3 arguments:

- the [URI](https://docs.expo.dev/versions/latest/sdk/filesystem/#api) of the file,
- its name (e.g. `my-document.pdf`),
- its MIME type (e.g. `application/pdf`).

Here is an example:

```typescript
// ...
import { MimeType } from "@logion/client";
import { ExpoFile } from '@logion/client-expo';
// ...

const fileName = "file.txt";
const file = new ExpoFile(`${FileSystem.cacheDirectory}/${fileName}`, fileName, MimeType.from("text/plain"));
```
See [documentation](https://logion-network.github.io/logion-api/).
2 changes: 1 addition & 1 deletion packages/client-node/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Use your favorite package manager (e.g. yarn) and install package `@logion/clien

## Usage

See [core client](../client/README.md).
See [documentation](https://logion-network.github.io/logion-api/).

## Integration tests

Expand Down
8 changes: 1 addition & 7 deletions packages/client-react-native-fs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,4 @@ Use your favorite package manager (e.g. yarn) and install package `@logion/clien

## Usage

This module provides `ReactNativeFsFile` and `ReactNativeFileUploader` classes.

An instance of `ReactNativeFileUploader` (use the zero-argument constructor) must be provided to `LogionClient.create(...)`.

`ReactNativeFsFile` instances (the constructor takes takes a single string argument, the path) must be passed to SDK whenever needed.

See [core client](../client/README.md).
See [documentation](https://logion-network.github.io/logion-api/).
256 changes: 1 addition & 255 deletions packages/client/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,258 +8,4 @@ Use your favorite package manager (e.g. yarn) and install package `@logion/clien

## Usage

### Authentication

```typescript
import { LogionClient, KeyringSigner } from '@logion/client';
import { Keyring } from '@polkadot/api';

const keyring = new Keyring();
keyring.addFromUri("0xe5be9a5092b81bca64be81d212e7f2f9eba183bb7a90954f7b76361f6edb5c0a"); // Alice
const signer = new KeyringSigner(keyring);

const client = await LogionClient.create({
rpcEndpoints: [ 'wss://rpc01.logion.network' ], // A list of websocket endpoints
directoryEndpoint: 'https://directory.logion.network', // A logion directory
buildFileUploader: ..., // A zero-argument function returning an instance of file uploader
});

// Authenticate Alice
const authenticatedClient = await client.authenticate([ "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY" ], signer);

// Use authenticatedClient to interact with the network
```

### Balance and Transactions

```typescript
// Balance
let balanceState = await authenticatedClient.balanceState();
const balance = balanceState.balances[0];
console.log("Balance :%s", `${balance.balance.coefficient.toInteger()}.${balance.balance.coefficient.toFixedPrecisionDecimals(2)}${balance.balance.prefix.symbol}`)

// Transactions
const transactions = balanceState.transactions;
console.log("First transaction destination: %s", transactions[0].destination)

// Transfer
balanceState = balanceState.transfer({
signer,
amount: new PrefixedNumber("2", KILO),
destination: ALICE.address
});
```

### Protection

```typescript
// Choose legal officers
const legalOfficers: LegalOfficer[] = authenticatedClient.getLegalOfficers();

const alice = legalOfficers[0];
const bob = legalOfficers[1];

// Request a protection
const noProtection = await authenticatedClient.protectionState() as NoProtection;
const pending = await noProtection.requestProtection({
legalOfficer1: alice,
legalOfficer2: bob,
userIdentity: {
email: "john.doe@invalid.domain",
firstName: "John",
lastName: "Doe",
phoneNumber: "+1234",
},
postalAddress: {
city: "",
country: "",
line1: "",
line2: "",
postalCode: "",
}
});

// ... Wait for LO's acceptance ...
const accepted = (await pending.refresh()) as AcceptedProtection;

// Activate the protection
accepted.activate(signer);
```

### Vault
Operations require an activated protection (see above "Protection")
```typescript
let activeProtection = (await authenticatedClient.protectionState()) as ActiveProtection;

// Transfer from vault
let vaultState = await activeProtection.vaultState();
const vaultAddress = vaultState.vaultAddress;
vaultState = await vaultState.createVaultTransferRequest({
legalOfficer: alice,
amount: new PrefixedNumber("1", NONE),
destination: REQUESTER_ADDRESS,
signer
});
const pendingRequest = vaultState.pendingVaultTransferRequests[0];

// ... Wait for LO's acceptance ...
vaultState = await vaultState.refresh();

// Check Vault balance
const balance = vaultState.balances[0];
console.log("Balance :%s", `${balance.balance.coefficient.toInteger()}.${balance.balance.coefficient.toFixedPrecisionDecimals(2)}${balance.balance.prefix.symbol}`)
```

### Recovery

```typescript
const NEW_ADDRESS = "5GsxAu1XexDATCbDJbWxKSow4gdC6epkajZr7Ht8Ci9VZabV";

const authenticatedClient = await LogionClient.create({
rpcEndpoints: [ 'wss://rpc01.logion.network' ], // A list of websocket endpoints
directoryEndpoint: 'https://directory.logion.network' // A logion directory
}).authenticate([ NEW_ADDRESS ], signer);

// Request a recovery
const noProtection = await authenticatedClient.protectionState() as NoProtection;
const pending = await noProtection.requestRecovery({
recoveredAddress: REQUESTER_ADDRESS,
signer,
legalOfficer1: alice,
legalOfficer2: bob,
userIdentity: {
email: "john.doe@invalid.domain",
firstName: "John",
lastName: "Doe",
phoneNumber: "+1234",
},
postalAddress: {
city: "",
country: "",
line1: "",
line2: "",
postalCode: "",
}
});

// ... Wait for LO's acceptance and vouching ...
const accepted = (await pending.refresh()) as AcceptedProtection;

// Activate the new protection
let pendingRecovery = await accepted.activate(signer) as PendingRecovery;
pendingRecovery = await pendingRecovery.waitForFullyReady();

// Claim
const claimed = await pendingRecovery.claimRecovery(signer);

// Recover the lost balance
const recoveredBalance = await claimed.recoveredBalanceState();
await recoveredBalance.transfer({
signer,
destination: NEW_ADDRESS,
amount: recoveredBalance.balances[0].available,
});

// Recover the lost vault
const newVault = await claimed.vaultState();
let recoveredVault = await claimed.recoveredVaultState();
recoveredVault = await recoveredVault.createVaultTransferRequest({
legalOfficer: alice,
amount: recoveredVault.balances[0].available,
destination: newVault.vaultAddress,
signer,
});

// ... Wait for LO's acceptance ...
newVault = await newVault.refresh();

// Check Vault balance
const newBalance = newVault.balances[0];
console.log("Balance :%s", `${newBalance.balance.coefficient.toInteger()}.${newBalance.balance.coefficient.toFixedPrecisionDecimals(2)}${newBalance.balance.prefix.symbol}`);
```

### Transaction Legal Officer Case (LOC)

```typescript
let locsState = await authenticatedClient.locsState();

// Request a Transaction LOC
const pendingRequest = await locsState.requestTransactionLoc({
legalOfficer: alice,
description: "This is a Transaction LOC",
// Below field is required only if the legal officer you are sending the request to
// does not already protect you (see Protection or Recovery).
userIdentity: {
email: "john.doe@invalid.domain",
firstName: "John",
lastName: "Doe",
phoneNumber: "+1234",
},
});

// ... Wait for LO's acceptance ...
let openLoc = await pendingRequest.refresh() as OpenLoc;

// Submit new elements to the LO through the LOC
openLoc = await openLoc.addMetadata({
name: "Some name",
value: "Some value"
});
const file: File = ...; // Platform dependent, see plugins
openLoc = await openLoc.addFile({
fileName: "id.jpeg",
nature: "ID",
file,
});

// ... Wait for the LO to publish elements and close the LOC ...
const closedLoc = await openLoc.refresh() as ClosedLoc;
```

### Collection LOC and items

```typescript
let locsState = await authenticatedClient.locsState();

// Request a collection LOC
const pendingRequest = await locsState.requestCollectionLoc({
legalOfficer: alice,
description: "This is a Collection LOC",
userIdentity: {
email: "john.doe@invalid.domain",
firstName: "John",
lastName: "Doe",
phoneNumber: "+1234",
},
});

// ... Wait for the LO to open the LOC with upload support, fill-it in then close it ...

let closedLoc = await openLoc.refresh() as ClosedCollectionLoc;

// Add an item to the collection LOC
const itemId = Hash.of("first-collection-item"); // Hash is provided by @logion/node-api
const itemDescription = "First collection item";
const file: File = ...; // Platform dependent, see plugins
closedLoc = await closedLoc.addCollectionItem({
itemId,
itemDescription,
signer,
itemFiles: [ // Must remain undefined with Collection LOCs without upload support
new ItemFileWithContent({
name: "test.txt",
contentType: MimeType.from("text/plain"),
hashOrContent: HashOrContent.fromContent(file), // Let SDK compute hash and size
})
]
});

// Later, retrieve the item given its ID
const item = await closedLoc.getCollectionItem({ itemId });
```

## Publication
In order to publish to [npm](https://www.npmjs.com/org/logion), you can use the following scripts:

* `yarn check-publish` - to check the published package content.
* `yarn do-publish` - to actually publish (require authentication with `npm adduser`)
See [documentation](https://logion-network.github.io/logion-api/).
22 changes: 2 additions & 20 deletions packages/crossmint/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,11 @@

This project provides some utility classes enabling the use of the
[Crossmint wallet](https://github.com/Crossmint/embed)
with a [logion client](https://github.com/logion-network/logion-api/tree/main/packages/client#readme).
with the [logion client](https://github.com/logion-network/logion-api/tree/main/packages/client#readme).

Note that only message signature is supported. So you will be able to authenticate and interact
with logion off-chain services, but not submit extrinsics to the logion chain.

## Usage

Install package `@logion/crossmint` with your favorite package manager and start siging content using the extension.

```typescript
import { CrossmintSigner } from '@logion/crossmint';

const crossmint = new CrossmintEVMWalletAdapter({
apiKey: "YOUR_API_KEY",
chain: BlockchainTypes.ETHEREUM, // Only Ethereum is supported for the moment
});

const address = await crossmint.connect();
if(!address) {
throw new Error("Unable to connect to Crossmint");
}

const client = LogionClient.create(...);
const signer = new CrossmintSigner(crossmint);
let authenticatedClient = await client.authenticate([ address ], signer);
```
See [documentation](https://logion-network.github.io/logion-api/).
16 changes: 1 addition & 15 deletions packages/extension/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,4 @@ with a [logion client](https://github.com/logion-network/logion-api/tree/main/pa

## Usage

Install package `@logion/extension` with your favorite package manager and start siging content using the extension.

```typescript
import { enableExtensions, ExtensionSigner } from '@logion/extension';

const client = LogionClient.create(...); // Create your logion client

const register = await enableExtensions("Your app name", [ "polkadot-js" ]);
const signer = new ExtensionSigner();
register((accounts: InjectedAccount[]) => {
const addresses = accounts.map(account => account.address);
const authenticated = await client.authenticate(addresses, signer); // This will enable authentication by signing with the extension
// Use authenticated to use logion features
});
```
See [documentation](https://logion-network.github.io/logion-api/).
14 changes: 1 addition & 13 deletions packages/multiversx/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,4 @@ with logion off-chain services, but not submit extrinsics to the logion chain.

## Usage

Install package `@logion/multiversx` with your favorite package manager and start siging content using the extension.

```typescript
import { MultiversxSigner } from '@logion/multiversx';

const signer = new MultiversxSigner();
const address = await signer.login();

const client = LogionClient.create(...);
const account = client.api.queries.getValidAccountId(address, "Bech32");

let authenticatedClient = await client.authenticate([ account ], signer);
```
See [documentation](https://logion-network.github.io/logion-api/).
Loading

0 comments on commit ee6d101

Please sign in to comment.