@arianee/creator
v1.84.0
Published
The creator library makes it easy for builders to create content on the Arianee protocol through a higher level API. It is essentially a wrapper around the `@arianee/arianee-protocol-client` and the `@arianee/arianee-privacy-gateway-client` libraries.
Downloads
1,381
Keywords
Readme
@arianee/creator
The creator library makes it easy for builders to create content on the Arianee protocol through a higher level API. It is essentially a wrapper around the @arianee/arianee-protocol-client
and the @arianee/arianee-privacy-gateway-client
libraries.
Installation
The library requires the @arianee/core
package, it is used for message and transaction signing / sending.
npm install @arianee/creator @arianee/core
Usage
Instantiate a new Creator
instance and pass the required params core
, creatorAddress
and transactionStrategy
.
import { Creator } from '@arianee/creator';
import { Core } from '@arianee/core';
const creator = new Creator({
core: Core.fromRandom(),
creatorAddress: '0x...',
transactionStrategy: 'WAIT_TRANSACTION_RECEIPT',
});
You then need to connect to the desired protocol instance using the connect
method, the parameter must be the protocol's slug (e.g. testnet
). This will set the connected
property of the Creator
instance to true
if the connection was successful. In case of failure, it will throw an error.
(async () => {
try {
const connected = await creator.connect('testnet');
console.log(connected); // true
} catch {
console.log('connection failed');
}
// you can also use creator.connected
console.log(creator.connected); // true
})();
Most methods of the library require a connection prior to being used. If you try to use a method without being connected, it will throw a NotConnectedError
.
Constructor
The constructor takes different parameters:
export type TransactionStrategy = 'WAIT_TRANSACTION_RECEIPT' | 'DO_NOT_WAIT_TRANSACTION_RECEIPT';
export type CreatorParams<T extends TransactionStrategy> = {
creatorAddress: string;
core: Core;
transactionStrategy: T;
fetchLike?: typeof fetch;
protocolDetailsResolver?: ProtocolDetailsResolver;
};
creatorAddress
: the address that will receive the Arianee protocol rewardscore
: an@arianee/core
instancetransactionStrategy
: either to wait for transaction receipt or not. The recommended value for most users is'WAIT_TRANSACTION_RECEIPT'
. If'WAIT_TRANSACTION_RECEIPT'
is passed, theCreator
will wait for the transaction receipt, ensuring that the transaction has been successful, and methods will return aContractTransactionReceipt
. If'DO_NOT_WAIT_TRANSACTION_RECEIPT'
is passed, theCreator
will not wait for the receipt and methods will return aContractTransactionResponse
. This means the transaction might fail without notification. The latter is suitable for programs that utilize transaction queues and cannot wait for transaction confirmations. If the@arianee/core
instance you are using has a customsendTransaction
method for queuing transactions (one that resolves to{ skipResponse: true }
), you need to use'DO_NOT_WAIT_TRANSACTION_RECEIPT'
.fetchLike
: this is the fetch-like function used for making HTTP requests. It can be any function that has the same signature as thefetch
function. By default, it uses thedefaultFetchLike
of@arianee/utils
.protocolDetailsResolver
: you can provide a custom protocol details resolver, it can be any function that has the same signature as theprotocolDetailsResolver
function of@arianee/arianee-protocol-client
.arianeeApiUrl
(optional): A string representing the Arianee API URL. The default value is'https://api.arianee.com'
.
Examples
We've built a minimalistic Angular application that leverages some of the @arianee/creator
features.
It can be ran with
npm run angular-creator
Code is available in the apps/angular-creator
folder.
You can also find examples of usage in the apps/arianee-sdk-example/creator
folder.
Main features
Creator features are separated by type:
- Smart assets
- Messages
- Events
- Utils
buyCredit
A method to buy smart asset, message, event or update credits.
public async buyCredit(
creditType: CreditType,
amount: number,
overrides: NonPayableOverrides = {}
)
Implementation example :
await this.creator.buyCredit(parseInt(this.creditType) as CreditType, parseInt(this.amount.trim()));
enum CreditType {
smartAsset = 0,
message = 1,
event = 2,
update = 3,
}
Smart assets
reserveSmartAssetId
Reserve a particular smart asset id that can be used later to create a smart asset.
public async reserveSmartAssetId(
id?: number,
overrides: NonPayableOverrides = {}
)
Implementation example :
await this.creator.smartAssets.reserveSmartAssetId(this.id ? parseInt(this.id.trim()) : undefined);
createAndStoreSmartAsset
⚠️ Requires the core address to have an identity URI.
Create a smart asset and store its content in the Arianee Privacy Gateway set in the core address's identity and return a LinkObject
.
public async createAndStoreSmartAsset(
params: CreateAndStoreSmartAssetParameters,
overrides: NonPayableOverrides = {}
) : Promise<LinkObject>
Implementation example :
await this.creator.smartAssets.createAndStoreSmartAsset({
smartAssetId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
content,
});
interface CreateAndStoreSmartAssetParameters {
smartAssetId?: number;
tokenAccess?: { fromPassphrase: string } | { address: string };
tokenRecoveryTimestamp?: number;
sameRequestOwnershipPassphrase?: boolean;
content: ArianeeProductCertificateI18N;
}
type LinkObject = {
smartAssetId: SmartAsset['certificateId'];
deeplink?: string;
passphrase?: string;
};
The method can throw different errors:
UnavailableSmartAssetIdError
if the smart asset id is not availableInsufficientSmartAssetCreditsError
if the core address does not have enough smart asset creditsNoIdentityError
if the core address does not have an identity URIArianeePrivacyGatewayError
if an error occurred while interacting with the Arianee privacy gateway
createSmartAsset
Create a smart asset and return a LinkObject
. This method does not store the content in the Arianee Privacy Gateway, use createAndStoreSmartAsset
instead if you need to.
public async createSmartAsset(
params: CreateSmartAssetParameters,
overrides: NonPayableOverrides = {}
): Promise<LinkObject>
Implementation example :
await this.creator.smartAssets.createSmartAsset({
smartAssetId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
uri: this.uri,
});
interface CreateSmartAssetParameters {
smartAssetId?: number;
tokenAccess?: { fromPassphrase: string } | { address: string };
tokenRecoveryTimestamp?: number;
sameRequestOwnershipPassphrase?: boolean;
uri: string;
}
type LinkObject = {
smartAssetId: SmartAsset['certificateId'];
deeplink?: string;
passphrase?: string;
};
The method can throw different errors:
UnavailableSmartAssetIdError
if the smart asset id is not availableInsufficientSmartAssetCreditsError
if the core address does not have enough smart asset credits
createSmartAssetRaw
Create a smart asset and return a LinkObject
. This method does not store the content in the Arianee Privacy Gateway nor retrieve the content from an URI, use createAndStoreSmartAsset
or createSmartAsset
instead if you need to.
public async createSmartAssetRaw(
params: CreateSmartAssetCommonParameters,
overrides: NonPayableOverrides = {}
): Promise<LinkObject>
Implementation example :
await this.creator.smartAssets.createSmartAssetRaw({
smartAssetId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
content,
});
interface CreateSmartAssetCommonParameters {
smartAssetId?: number;
tokenAccess?: { fromPassphrase: string } | { address: string };
tokenRecoveryTimestamp?: number;
sameRequestOwnershipPassphrase?: boolean;
content: ArianeeProductCertificateI18N;
}
type LinkObject = {
smartAssetId: SmartAsset['certificateId'];
deeplink?: string;
passphrase?: string;
};
The method can throw different errors:
UnavailableSmartAssetIdError
if the smart asset id is not availableInsufficientSmartAssetCreditsError
if the core address does not have enough smart asset credits
updateSmartAsset
Update the certificate content imprint on chain. Returns the imprint of the new content.
public async updateSmartAsset(
smartAssetId: SmartAsset['certificateId'],
content: SmartAsset['content'],
overrides: NonPayableOverrides = {}
): Promise<{ imprint: string }>
Implementation example :
await this.creator.smartAssets.updateSmartAsset(this.smartAssetId, content);
The method can throw different errors:
InsufficientUpdateCreditsError
if the core address does not have enough update creditsArianeePrivacyGatewayError
if an error occurred while interacting with the Arianee privacy gateway
updateAndStoreSmartAsset
⚠️ Requires the core address to have an identity URI.
Update the content of a smart asset in the Arianee privacy gateway and update its imprint on chain. Returns the imprint of the new content.
public async updateAndStoreSmartAsset(
smartAssetId: SmartAsset['certificateId'],
content: SmartAsset['content'],
overrides: NonPayableOverrides = {}
): Promise<{ imprint: string }>
Implementation example :
await this.creator.smartAssets.updateAndStoreSmartAsset(this.smartAssetId, content);
The method can throw different errors:
InsufficientUpdateCreditsError
if the core address does not have enough update creditsNoIdentityError
if the core address does not have an identity URIArianeePrivacyGatewayError
if an error occurred while interacting with the Arianee privacy gateway
recoverSmartAsset
A method to recover a smart asset issued by the core address.
public async recoverSmartAsset(
id: string,
overrides: NonPayableOverrides = {}
)
Implementation example :
await this.creator.smartAssets.recoverSmartAsset(this.id);
destroySmartAsset
A method to destroy a smart asset owned by the core address.
public async destroySmartAsset(
id: string,
overrides: NonPayableOverrides = {}
)
Implementation example :
await this.creator.smartAssets.destroySmartAsset(this.id);
setTokenAccess
A method to set the token access (request / view) of a smart asset owned by the core address.
public async setTokenAccess(
smartAssetId: SmartAsset['certificateId'],
tokenAccessType: TokenAccessType,
tokenAccess?: TokenAccess,
overrides: NonPayableOverrides = {}
): Promise<LinkObject>
setRequestKey
A method to set the request key of a smart asset owned by the core address.
public async setRequestKey(
smartAssetId: SmartAsset['certificateId'],
tokenAccess?: TokenAccess,
overrides: NonPayableOverrides = {}
): Promise<LinkObject>
Implementation example :
await this.creator.smartAssets.setRequestKey(this.id, tokenAccess);
updateTokenURI
Update the public URI of a smart asset.
public async updateTokenURI(
smartAssetId: SmartAsset['certificateId'],
uri: string,
overrides: NonPayableOverrides = {}
)
Implementation example :
await this.creator.smartAssets.updateTokenURI(this.id, this.uri);
The method can throw:
NotIssuerError
if the core address is not the issuer of the smart assetInvalidURIError
if the uri is not valid
Messages
createAndStoreMessage
⚠️ Requires the core address to have an identity URI.
Create a message and store its content in the Arianee Privacy Gateway set in the core address's identity and return a CreatedMessage
.
public async createAndStoreMessage(
params: CreateAndStoreMessageParameters,
overrides: NonPayableOverrides = {}
): Promise<CreatedMessage>
Implementation example :
await this.creator.messages.createAndStoreMessage({
smartAssetId: parseInt(this.smartAssetId),
content,
messageId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
});
type CreatedMessage = {
imprint: string;
id: number;
};
interface CreateAndStoreMessageParameters {
messageId?: number;
smartAssetId: number;
content: ArianeeMessageI18N;
}
The method can throw:
InsufficientMessageCreditsError
if the core address does not have enough message creditsUnavailableMessageIdError
if the message id is not availableNoIdentityError
if the core address does not have an identity URIArianeePrivacyGatewayError
if an error occurred while interacting with the Arianee privacy gateway
createMessage
Create a message and return a CreatedMessage
.
public async createMessage(
params: CreateMessageParameters,
overrides: NonPayableOverrides = {}
): Promise<CreatedMessage>
Implementation example :
await this.creator.messages.createMessage({
smartAssetId: parseInt(this.smartAssetId),
uri: this.uri,
messageId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
});
type CreatedMessage = {
imprint: string;
id: number;
};
interface CreateMessageParameters {
messageId?: number;
smartAssetId: number;
uri: string;
}
The method can throw:
InsufficientMessageCreditsError
if the core address does not have enough message creditsUnavailableMessageIdError
if the message id is not available
createMessageRaw
Create a message and return a CreatedMessage
. This method does not store the content in the Arianee Privacy Gateway nor retrieve the content from an URI, use createAndStoreMessage
or createMessage
instead if you need to.
public async createMessageRaw(
params: CreateMessageCommonParameters,
overrides: NonPayableOverrides = {}
): Promise<CreatedMessage>
Implementation example :
await this.creator.messages.createMessageRaw({
smartAssetId: parseInt(this.smartAssetId),
content,
messageId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
});
type CreatedMessage = {
imprint: string;
id: number;
};
interface CreateMessageCommonParameters {
messageId?: number;
smartAssetId: number;
content: ArianeeMessageI18N;
}
The method can throw:
InsufficientMessageCreditsError
if the core address does not have enough message creditsUnavailableMessageIdError
if the message id is not available
Events
createAndStoreEvent
⚠️ Requires the core address to have an identity URI if not using true for useSmartAssetIssuerPrivacyGateway
.
Create an event and store its content in the Arianee Privacy Gateway set in the smart issuer's identity (or the core address's identity if useSmartAssetIssuerPrivacyGateway
set to false) and return a CreatedEvent
.
Note on useSmartAssetIssuerPrivacyGateway
, the default value is true
. This means that default behaviour when using createAndStoreEvent
is that the event content will be stored in the smart asset issuer`s privacy gateway instead of the event issuer's privacy gateway.
public async createAndStoreEvent(
params: CreateAndStoreEventParameters,
overrides: NonPayableOverrides = {}
): Promise<CreatedEvent>
Implementation example :
await this.creator.events.createAndStoreEvent({
smartAssetId: parseInt(this.smartAssetId),
content,
eventId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
});
type CreatedEvent = {
imprint: string;
id: number;
};
interface CreateAndStoreEventParameters {
eventId?: number;
smartAssetId: number;
content: ArianeeEventI18N;
useSmartAssetIssuerPrivacyGateway?: boolean;
}
The method can throw:
InsufficientEventCreditsError
if the core address does not have enough event creditsUnavailableEventIdError
if the event id is not availableNoIdentityError
if the core address does not have an identity URIArianeePrivacyGatewayError
if an error occurred while interacting with the Arianee privacy gateway
createEvent
Create an event and return a CreatedEvent
.
public async createEvent(
params: CreateEventParameters,
overrides: NonPayableOverrides = {}
): Promise<CreatedEvent>
Implementation example :
await this.creator.events.createEvent({
smartAssetId: parseInt(this.smartAssetId),
uri: this.uri,
eventId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
});
type CreatedEvent = {
imprint: string;
id: number;
};
interface CreateEventParameters {
eventId?: number;
smartAssetId: number;
uri: string;
}
The method can throw:
InsufficientEventCreditsError
if the core address does not have enough event creditsUnavailableEventIdError
if the event id is not available
createEventRaw
Create an event and return a CreatedEvent
. This method does not store the content in the Arianee Privacy Gateway nor retrieve the content from an URI, use createAndStoreEvent
or createEvent
instead if you need to.
public async createEventRaw(
params: CreateEventCommonParameters,
overrides: NonPayableOverrides = {}
): Promise<CreatedEvent>
Implementation example :
await this.creator.messages.createEventRaw({
smartAssetId: parseInt(this.smartAssetId),
content,
eventId: this.id && this.id !== '' ? parseInt(this.id) : undefined,
});
type CreatedEvent = {
imprint: string;
id: number;
};
interface CreateEventCommonParameters {
eventId?: number;
smartAssetId: number;
content: ArianeeMessageI18N;
}
The method can throw:
InsufficientEventCreditsError
if the core address does not have enough event creditsUnavailableEventIdError
if the event id is not available
storeEvent
⚠️ Requires the core address to have an identity URI if not using true for useSmartAssetIssuerPrivacyGateway
.
Store content of the event in the Arianee Privacy Gateway set in the smart issuer's identity (or the core address's identity if useSmartAssetIssuerPrivacyGateway
set to false).
public async storeEvent(
smartAssetId: number,
eventId: number,
content: CreateAndStoreEventParameters['content'],
useSmartAssetIssuerPrivacyGateway = true
)
The method can throw:
NoIdentityError
if the core or issuer address does not have an identity URIArianeePrivacyGatewayError
if an error occurred while interacting with the Arianee privacy gateway
Identities
updateIdentity
⚠️ Requires the core address to have an identity URI.
Updates the identity of the core address with passed URI and imprint.
public async updateIdentity(
{
uri,
imprint,
}: {
uri: string;
imprint: string;
},
overrides: NonPayableOverrides = {}
)
The method can throw:
NoIdentityError
if the core address does not have an identity URI
Utils
isSmartAssetIdAvailable
A method to check if the passed smart asset id is available.
public async isSmartAssetIdAvailable(id: number): Promise<boolean>
canCreateSmartAsset
A method to check if the creator's address can create the smart asset with the passed id.
public async canCreateSmartAsset(id: number): Promise<boolean>
getCreditBalance
Get the balance of the passed credit type. If address is not passed, the creator's address will be used.
public async getCreditBalance(
creditType: CreditType,
address?: string
): Promise<bigint>
getCreditPrice
Get the credit price of the passed credit type on the current protocol.
public async getCreditPrice(creditType: CreditType): Promise<bigint>
getAriaBalance
Get the aria balance. If address is not passed, the creator's address will be used.
public async getAriaBalance(address?: string): Promise<bigint>
getNativeBalance
Get the native balance. If address is not passed, the creator's address will be used.
public async getNativeBalance(address?: string): Promise<bigint>
getAvailableSmartAssetId
Return a randomly generated available smart asset id.
public async getAvailableSmartAssetId(): Promise<number>
getAriaAllowance
Return the aria allowance of the passed address for the passed spender address. If the address is not passed, the creator's address will be used.
public async getAriaAllowance(spender: string, address?: string)
approveAriaSpender
Approve the passed spender for the passed amount on the aria contract.
public async approveAriaSpender(
spender: string,
amount: BigNumberish = '10000000000000000000000000000'
)
getSmartAssetOwner
Get the owner of the passed smart asset id.
public async getSmartAssetOwner(id: string): Promise<string>
calculateImprint
Calculate the imprint of the passed content.
public async calculateImprint(
content: ArianeeProductCertificateI18N
): Promise<string>
requestTestnetAria20
For developers, only available on testnet
Request testnet aria20 tokens, if address is not passed, the creator's address will be used.
public async requestTestnetAria20(address?: string)
The method can throw:
ProtocolCompatibilityError
if called on a protocol that is not the testnet protocol
getSmartAssetIssuer
A method to get the issuer of a smart asset.
public async getSmartAssetIssuer(id: string)
getSmartAssetIssuer
A method to get the issuer of a smart asset.
public async getSmartAssetIssuer(id: string)
getAvailableId
A method to get a randomly generated available id for the passed type.
public async getAvailableId(
idType: 'smartAsset' | 'message' | 'event'
): Promise<number>
getAvailableSmartAssetId
A method to get a randomly generated available id for the a smart asset.
public async getAvailableSmartAssetId(): Promise<number>
getAvailableMessageId
A method to get a randomly generated available id for the a message.
public async getAvailableMessageId(): Promise<number>
isMessageIdAvailable
A method to check whether or not a given id is available for use as a message id.
public async isMessageIdAvailable(id: number): Promise<boolean>
Tests
Unit tests can be ran with:
npm run test:creator